# KEY711 Image and Video API Guide

OriginGateway image prices and Seedance CH0113 / seedance W-zq video prices are generated automatically from the current server catalog whenever this guide is fetched. All listed retail prices are in Malaysian ringgit (RM). Live account permissions and authenticated quotes take precedence over public base-group prices.

This guide describes the KEY711 gateway, not a direct integration with its upstream providers. Examples contain placeholders only. They have been checked against the local routes and configuration; this documentation update did not perform paid generation tests for every model.

## 1. Connection and authentication

The production API origin is `https://api711.my`. Use this HTTPS address for all KEY711 API requests. The WordPress shop domain `https://key711.com` is not an API endpoint.

| Setting | Value |
| --- | --- |
| Origin | `https://api711.my` |
| OpenAI-compatible SDK base URL | `https://api711.my/v1` |
| Authorization | `Bearer <KEY711_API_KEY>` |
| Model | An exact ID returned for your key by `GET /v1/models` |

Create a KEY711 key with the appropriate group and model permissions. Do not use an upstream channel secret. Browser login cookies are not a substitute for API authentication. In an API-key input field, enter only the key; add `Bearer ` only when constructing the Authorization header.

Keep keys on your backend, outside source control, logs and browser bundles. A key's group controls routing and pricing. Do not add a `group` property to generation requests.

The shell examples expect these environment variables to be set privately:

```bash
export KEY711_BASE_URL='https://api711.my'
export KEY711_API_KEY='<YOUR_KEY711_API_KEY>'

curl --fail-with-body "$KEY711_BASE_URL/v1/models" \
  -H "Authorization: Bearer $KEY711_API_KEY"
```

The examples use an origin without `/v1`; the endpoint paths include it. Avoid `/v1/v1`.

## 2. Endpoint directory

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/v1/models` | Models accessible to the key |
| POST | `/v1/images/generations` | Synchronous text-to-image |
| POST | `/v1/images/edits` | Synchronous image editing |
| POST | `/v1beta/models/{model}:generateContent` | Nano Banana / Gemini image generation and reference editing |
| GET | `/v1/video/models` | Available video models, capabilities and RM quotes |
| POST | `/v1/video/reference-images` | Upload one video reference image |
| POST | `/v1/videos` | Submit a video task using JSON |
| GET | `/v1/videos/{id}` | Read video status |
| GET | `/v1/videos/{id}/content` | Download completed video with authentication |

Image-batch endpoints are **not installed on this KEY711 deployment**. Do not call `/v1/image-batches/*`, use its batch cancellation/retry protocol, or assume its idempotency behavior exists here. Image streaming, variations and `file_id` image references are also outside this documented integration.

## 3. Image models and prices

<!-- KEY711_LIVE_IMAGE_PRICES_START -->

Current public base-group prices, calculated by the same server quote as Creator. Downloads are snapshots; refresh for current prices. Use one output per request and do not infer multi-output or optional-parameter support.

| Key group | Exact model ID | RM unit price | Billing unit | Protocol |
| --- | --- | ---: | --- | --- |
| `GPT-Image-4K` | `gpt-image-2-4k-high` | 0.10 | per request | Image API |
| `GPT-Image-4K` | `gpt-image-2-4k` | 0.10 | per request | Image API |
| `GPT-Image-4K` | `gpt-image-2.5-flare-4k` | 0.13 | per request | Image API |
| `GPT-Image-4K` | `gpt-image-2.5-sunburst-4k` | 0.13 | per request | Image API |
| `GPT-Image-官渠` | `gpt-image-2.5-flare` | 0.20 | per request | Image API |
| `GPT-Image-官渠` | `gpt-image-2.5-sunburst` | 0.20 | per request | Image API |
| `GPT-Image` | `gpt-image-2.5-flare` | 0.03 | per request | Image API |
| `GPT-Image` | `gpt-image-2.5-sunburst` | 0.03 | per request | Image API |
| `GPT-Image` | `gpt-image-2` | 0.03 | per request | Image API |
| `Grok-imagine-image` | `grok-imagine-image-2.0` | 0.08 | per request | Image API |
| `Grok-imagine-image` | `grok-imagine-image` | 0.06 | per request | Image API |
| `Nano Banana` | `gemini-3-pro-image-preview` | 0.08 | per request | Gemini native |
| `Nano Banana` | `gemini-3.1-flash-image-preview` | 0.06 | per request | Gemini native |
| `Nano Banana` | `gemini-nano-banana-2.1` | 0.08 | per request | Gemini native |
| `Nano Banana` | `nano-banana-2.1` | 0.08 | per request | Gemini native |
| `Nano Banana` | `nano-banana-2` | 0.06 | per request | Gemini native |
| `Nano Banana` | `nano-banana-pro` | 0.08 | per request | Gemini native |

<!-- KEY711_LIVE_IMAGE_PRICES_END -->

### Nano Banana and Grok groups

Available IDs are restricted to each upstream key's authorized catalog. Prices and units above come from live group-adjusted metadata, with the displayed numeric amount used 1:1 as RM, rounded half-up to two decimal places. No currency conversion or markup is added to OriginGateway. Missing, conflicting, token-priced or unreviewed contracts remain unavailable pending review. Do not infer batch pricing or guaranteed resolution from model names or prices. No paid generation was performed to verify optional parameters.

#### Nano Banana generation

Use a key in the `Nano Banana` group. The exact model ID belongs in the URL, not an OpenAI `model` body field. Listed Gemini-native aliases use this example structure:

```bash
curl --fail-with-body --connect-timeout 30 --max-time 720 \
  "$KEY711_BASE_URL/v1beta/models/nano-banana-2:generateContent" \
  -H "Authorization: Bearer $KEY711_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"Generate one image of a green glass bottle on a white studio background."}]}],
    "generationConfig": {"responseModalities":["TEXT","IMAGE"]}
  }'
```

For reference-image editing, replace the `parts` array with:

```json
[
  {"text":"Keep the subject and replace the background with a white studio."},
  {"inlineData":{"mimeType":"image/png","data":"<BASE64_IMAGE_DATA>"}}
]
```

Encode your image file as base64 and replace the placeholder. `inlineData.data` contains base64 bytes only, without a `data:image/...` prefix. Do not send `prompt`, `n`, `size`, multipart files or `/v1/images/generations` for this native Gemini route. `generationConfig.imageConfig` controls such as `aspectRatio` are optional and depend on the upstream alias; begin with the minimal request rather than assuming all aliases have identical output tiers.

Read `candidates[].content.parts[]`. Save image parts by base64-decoding `inlineData.data` and respecting `inlineData.mimeType`; other parts may contain text. Check errors, safety blocking and empty candidates before claiming an image was generated. Model IDs and the native endpoint are confirmed from the upstream catalog; optional-field compatibility still needs a generation test.

#### Grok generation and reference editing

Use a key in `Grok-imagine-image`. Generate via `POST /v1/images/generations`:

```json
{
  "model": "grok-imagine-image-2.0",
  "prompt": "A green glass bottle on a white studio background.",
  "n": 1
}
```

For editing, send JSON to `POST /v1/images/edits`:

```bash
curl --fail-with-body --connect-timeout 30 --max-time 720 \
  "$KEY711_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $KEY711_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"grok-imagine-image-2.0",
    "prompt":"Keep the subject and replace the background with a white studio.",
    "n":1,
    "image":{"type":"image_url","url":"https://YOUR_PUBLIC_IMAGE_HOST/input.png"}
  }'
```

Replace the reference URL with an accessible image you have permission to share. A base64 data URI is also a provider-supported reference format. Read `data[].url` or `data[].b64_json`; optional `response_format` selects `url` or `b64_json`. Native protocol references: [Grok image API](https://docs.x.ai/developers/model-capabilities/imagine) and [Gemini image generation](https://ai.google.dev/gemini-api/docs/image-generation). These references describe formats, not KEY711 pricing or a guarantee of every upstream alias. GPT-specific masks, file limits and 4K target sizes below do not apply to these two groups.

### GPT-Image groups

Use the group and exact local model ID in the live table above. Do not rename every model to `gpt-image-2`: the supplied upstream document uses a token-based naming scheme that differs from KEY711's current separate IDs. The GPT-Image routes retain their existing mapping and channel credentials.

Use **`n: 1`** for this integration. The standard group currently uses a fixed-per-request expression, not a per-output multiplier. Do not extrapolate a multi-image price from the single-image amount. The upstream guide limits standard synchronous requests to 1-4 images and 4K synchronous requests to one; KEY711's pricing for larger batches must be agreed separately.

### Text-to-image

```bash
curl --fail-with-body --connect-timeout 30 --max-time 720 \
  "$KEY711_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $KEY711_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A studio photograph of a green glass bottle on a white background, no text.",
    "n": 1
  }'
```

| Field | Type | Guidance |
| --- | --- | --- |
| `model` | string | Required; an exact authorized KEY711 model ID |
| `prompt` | string | Required, nonempty description |
| `n` | integer | Use `1` |
| `size` | string | Optional target dimensions such as `1536x1024`; use ASCII `x` |
| `quality` | string | Upstream's supplied guide documents `auto` and `high` for `gpt-image-2` |
| `response_format` | string | That guide documents `url` and `b64_json`; omitted in minimal examples for compatibility |

The gateway accepts the optional fields above. This does not prove every current sunburst/flare/4K alias supports every combination. Optional-field compatibility and exact output dimensions remain provider-dependent. Do not rely on `style`, `background`, `moderation`, arbitrary custom fields or streaming for this integration. `quality: high` alone does not select a 4K route.

An illustrative response:

```json
{
  "created": 1790812800,
  "data": [{ "url": "https://image-host.example/result.png" }]
}
```

Process every element of `data`. Each image may contain `url` or `b64_json`. A response may also include `revised_prompt` and usage metadata; token counts in usage do not override the configured fixed image price.

For `url`, download from the returned media host **without forwarding your KEY711 Authorization header**. For `b64_json`, decode the base64 and save the bytes. Do not assume URLs are permanent; save results you need to retain. Validate external media URLs and file sizes in your own backend before downloading.

### 4K target sizes

Choose a listed KEY711 4K model with a `GPT-Image-4K` key. For example:

```json
{
  "model": "gpt-image-2-4k",
  "prompt": "A green glass bottle on a white studio background, no text.",
  "n": 1,
  "size": "3840x2160"
}
```

These target sizes apply to the 4K route. They are reference values, not an end-to-end verification of every KEY711 alias:

| Ratio | Target `size` | Ratio | Target `size` |
| --- | --- | --- | --- |
| 1:1 | `2880x2880` | 5:4 | `3200x2560` |
| 4:5 | `2560x3200` | 4:3 | `3264x2448` |
| 3:4 | `2448x3264` | 3:2 | `3504x2336` |
| 2:3 | `2336x3504` | 16:9 | `3840x2160` |
| 9:16 | `2160x3840` | 21:9 | `3696x1584` |

The upstream "4K" label is not a guarantee of 4096 pixels on every edge or ratio. Standard compatibility defaults such as `1024x1024` are not 4K targets.

### Image editing with a reference image

Use multipart, especially for 4K. Let curl or your HTTP client generate the multipart boundary.

```bash
curl --fail-with-body --connect-timeout 30 --max-time 720 \
  "$KEY711_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $KEY711_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=Keep the bottle shape and replace the background with a white studio.' \
  -F 'n=1' \
  -F 'image=@input.png'
```

For multiple references, replace `image=@input.png` with repeated fields such as `image[]=@a.png` and `image[]=@b.png`. For an edit mask, add `mask=@mask.png`; the upstream guide describes transparent areas as editable and opaque areas as preserved. Use a mask matching the source image dimensions.

For standard image routes, the gateway can forward JSON `image` or `images` with accessible public image URLs or data URLs. The upstream guide documents these forms for `gpt-image-2`; do not use `image_url`. Do not assume JSON references work for 4K edits: use multipart files there. These image-edit inputs are separate from the stricter video-reference URL rules below.

Upstream's documented input limits are 10 images, 25 MB per image, 150 MB total and 33,554,432 pixels per image. Gateway/proxy limits can be lower. Start with one small reference and confirm the chosen alias accepts it. Do not upload private or third-party media without the necessary rights and consent.

### Python example

Install `requests` in your application environment. This example saves the first base64 result or prints its media URL:

```python
import base64
import os
from pathlib import Path
import requests

base = os.environ["KEY711_BASE_URL"].rstrip("/")
response = requests.post(
    base + "/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["KEY711_API_KEY"]},
    json={"model": "gpt-image-2", "prompt": "A green bottle on white.", "n": 1},
    timeout=(30, 720),
)
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result-image.bin").write_bytes(base64.b64decode(item["b64_json"]))
else:
    print(item["url"])
```

Synchronous images may take several minutes. Allow at least 700 seconds at the client and verify your deployment's proxy timeout separately. A client timeout does not cancel a provider job or prove that no charge occurred. Do not blindly replay generation requests.

## 4. Video models and prices

Model availability, prices and limits change as channels synchronize. Before each submission flow, query **`GET /v1/video/models` with the same key**. Only models returned there are currently available to that key. Do not use a saved price table as a current quote.

`I/V/A` means maximum reference images/videos/audio clips, not output count. A range such as 4-15 means whole seconds in the saved catalog; use the actual `durations_seconds` array at runtime. Each task produces one video. Do not send `n` to batch video generation.

### Groups and channel compatibility

Select a group when creating the key, not in the generation request. Keep the same KEY711 base URL, bearer authentication, `POST /v1/videos`, polling and download endpoints across groups. Only change the model and its supported settings. New groups become usable after their routing, pricing and capability synchronization is enabled; a name in this guide is not an availability guarantee.

`Seedance CH0113` uses the same KEY711 contract, including model IDs such as `ch0113-sd-2.0-720p-mini`. Send `seconds` and `images` / `videos` / `audios` arrays. Do not send provider-only `duration`, `mode`, nested `references` or `client_task_id`. KEY711 translates these internally. Re-upload references after changing channels; upload URLs are channel-specific and may expire.

`seedance W-zq` is one local group with these approved video identities: `seedance-2.0`, `seedance-2.5`, `seedance-2.5-once`, `seedance-2.0-offical`, `H3`, `wan3.0-video`, and `wan3.0-yuanlian`. Keep the exact upstream spelling `offical` in requests. Availability requires the current authenticated catalog; public listings do not grant permission. Use the same KEY711 API and explicitly select `resolution` from `GET /v1/video/models`. Prices vary by resolution; use the current RM quote and its billing unit from the authenticated catalog. Per-second and per-task prices remain separate; `seedance-2.5-once` is conservatively fixed at 30 seconds, 720p, with zero video references. `wan3.0-video` also permits zero video references. H3 supports 4-15 seconds at 720p, up to 9 images and 3 audio references; video references are disabled because upstream support is not advertised. Upload local references through KEY711 before submission; never send provider-only `duration` or `reference_*_urls` fields.

`seedance-2.0-offical` supports 4-15 seconds, 480p/720p/1080p and the administrator-confirmed upstream limits of 9 images, 3 videos, 3 audio files and ratios 9:16, 16:9, 1:1, 3:4, 4:3. This model has separate prices with and without a reference video. For a chosen resolution, use `price.by_resolution[resolution]` without video references and its `with_reference_video` quote when the submitted `videos` array is nonempty. The server derives this billing condition from validated references; do not send `has_video` as a request parameter. The live tables below expose both cases.

W-zq duration, resolution and individual reference limits come from authenticated upstream descriptions, with the official 2.0 reference counts and ratios confirmed by the administrator where upstream metadata omits them. Unpublished prompt, combined-reference and file rules are not verified upstream limits: `limit_sources` distinguishes KEY711 input protections and `unverified_rules` records unknowns. WAN fixed aspect ratios follow the [official WAN API conventions](https://docs.modelstudio.console.alibabacloud.com/en/model-studio/wan3-video-generation-guide); this does not claim paid route execution has been tested. A verified model is withdrawn when its authorization or usable group disappears, and restored when a compatible authenticated contract returns. Announcements alone do not establish availability while the APIs keep advertising the model. Future identities, conflicting routes, billing grammar or currency metadata await review rather than a guessed quote.

### CH0113 and W-zq price policy

From 14 October 2026, these two groups use their upstream numeric prices 1:1 as RM retail amounts, rounded half-up to two decimal places, without the former 40% markup or an additional currency conversion. CH0113 uses the API quote, not a separate spreadsheet. W-zq uses the authenticated upstream group-adjusted displayed amount. Other groups retain their existing policies.

Model Square, Video Studio, canvas video settings and the public API use the same synchronized server pricing. The existing model-update task checks the upstream catalog every minute when enabled; updates become public only after validated pricing and routing are committed. Refresh the model list or reopen the canvas video settings before preparing a new task. `GET /v1/video/models` with your actual key is the authoritative quote. Applicable account discounts are reflected in that key's quote.

The following tables are rendered from the public Creator catalog on every document request, including Markdown downloads, without a separate stored price list. They include only verified, published models in these groups. Compatible new CH0113 identities are discovered automatically; unapproved W-zq identities and conflicting or incomplete contracts remain pending review. No whitelist, account permission or billing protection is widened by viewing this guide. If a quote is unavailable, an old price is not used as a fallback.

<!-- KEY711_LIVE_VIDEO_PRICES_START -->

Generated at 2026-11-03T12:49:33Z from the same public base-group quote used by Creator. These are not account-specific discounts. Reopen or refresh the page to fetch current prices; downloaded files are snapshots at download time. No generation request is made.

#### Seedance CH0113

| Exact model ID | Resolution | RM unit price | Billing unit | Reference video |
| --- | --- | ---: | --- | --- |
| `1311-seedance-2-5-1080p` | 1080p | 1.80 | per second | Any |
| `1311-seedance-2-5-480p` | 480p | 0.80 | per second | Any |
| `1311-seedance-2-5-720p` | 720p | 1.20 | per second | Any |
| `ch0101-sd-2.0-480p` | 480p | 0.92 | per second | Any |
| `ch0101-sd-2.0-720p` | 720p | 1.16 | per second | Any |
| `ch0102-sd-2.0-1080p` | 1080p | 1.60 | per second | Any |
| `ch0102-sd-2.0-720p` | 720p | 1.40 | per second | Any |
| `ch0107-sd-2.5-480p` | 480p | 1.04 | per second | Any |
| `ch0107-sd-2.5-720p` | 720p | 1.50 | per second | Any |
| `ch0108-sd-2.5-720p` | 720p | 1.80 | per second | Any |
| `ch0112-sd-2.0-480p-fast` | 480p | 0.70 | per second | Any |
| `ch0112-sd-2.0-720p-fast` | 720p | 1.12 | per second | Any |
| `ch0113-sd-2.0-480p-mini` | 480p | 0.50 | per second | Any |
| `ch0113-sd-2.0-720p-mini` | 720p | 0.76 | per second | Any |
| `ch1306-sd-2.0-480p` | 480p | 7.00 | per task | Any |
| `ch1306-sd-2.0-720p` | 720p | 10.00 | per task | Any |
| `ch1307-sd-2.5-720p` | 720p | 1.50 | per second | Any |
| `ch1308-sd-2.0-720p` | 720p | 1.10 | per second | Any |
| `ch1309-sd-2.0-480p` | 480p | 0.48 | per second | Any |
| `ch1309-sd-2.0-720p` | 720p | 0.68 | per second | Any |
| `ch1310-sd-2.5-720p` | 720p | 18.00 | per task | Any |

#### seedance W-zq

| Exact model ID | Resolution | RM unit price | Billing unit | Reference video |
| --- | --- | ---: | --- | --- |
| `H3` | 720p | 0.05 | per second | Any |
| `seedance-2.0` | 480p | 0.42 | per second | Any |
| `seedance-2.0` | 720p | 0.54 | per second | Any |
| `seedance-2.0-fast` | 480p | 0.18 | per second | Any |
| `seedance-2.0-fast` | 720p | 0.37 | per second | Any |
| `seedance-2.0-fast-token` | 480p | 17.75 | per million billing tokens; totals before generation are estimates | None |
| `seedance-2.0-fast-token` | 480p | 10.56 | per million billing tokens; totals before generation are estimates | Included |
| `seedance-2.0-fast-token` | 720p | 17.75 | per million billing tokens; totals before generation are estimates | None |
| `seedance-2.0-fast-token` | 720p | 10.56 | per million billing tokens; totals before generation are estimates | Included |
| `seedance-2.0-mini` | 480p | 0.09 | per second | Any |
| `seedance-2.0-mini` | 720p | 0.19 | per second | Any |
| `seedance-2.0-mini-token` | 480p | 8.28 | per million billing tokens; totals before generation are estimates | None |
| `seedance-2.0-mini-token` | 480p | 5.04 | per million billing tokens; totals before generation are estimates | Included |
| `seedance-2.0-mini-token` | 720p | 8.28 | per million billing tokens; totals before generation are estimates | None |
| `seedance-2.0-mini-token` | 720p | 5.04 | per million billing tokens; totals before generation are estimates | Included |
| `seedance-2.0-offical` | 1080p | 3.56 | per second | None |
| `seedance-2.0-offical` | 1080p | 4.32 | per second | Included |
| `seedance-2.0-offical` | 480p | 0.66 | per second | None |
| `seedance-2.0-offical` | 480p | 0.81 | per second | Included |
| `seedance-2.0-offical` | 720p | 1.43 | per second | None |
| `seedance-2.0-offical` | 720p | 1.73 | per second | Included |
| `seedance-2.5` | 1080p | 1.40 | per second | Any |
| `seedance-2.5` | 480p | 0.50 | per second | Any |
| `seedance-2.5` | 720p | 0.78 | per second | Any |
| `wan3.0-nsfw` | 1080p | 1.21 | per second | Any |
| `wan3.0-nsfw` | 480p | 0.29 | per second | Any |
| `wan3.0-nsfw` | 720p | 0.59 | per second | Any |
| `wan3.0-video` | 1080p | 1.45 | per second | Any |
| `wan3.0-video` | 480p | 0.36 | per second | Any |
| `wan3.0-video` | 720p | 0.72 | per second | Any |
| `wan3.0-yuanlian` | 1080p | 0.66 | per second | Any |
| `wan3.0-yuanlian` | 480p | 0.17 | per second | Any |
| `wan3.0-yuanlian` | 720p | 0.33 | per second | Any |

`wan3.0-nsfw`: billable seconds are ceil(total reference-video seconds) + ceil(output seconds). Images and audio do not add reference-video seconds. The unrounded video input plus output must not exceed 30 seconds. Totals in the model catalog exclude reference duration; include it when estimating a referenced task. Completion uses upstream reported billable duration; missing measured usage retains the reservation and requires reconciliation.

<!-- KEY711_LIVE_VIDEO_PRICES_END -->

Use `price.by_resolution[resolution].totals` for multi-resolution models, or `price.totals` for a fixed-resolution model. Per-second totals depend on the allowed duration; a per-task price is charged once, not multiplied by the video duration.

The server reserves the quoted task cost on submission and settles against the task's frozen billing expression and validated usage. A price update applies to new submissions; already submitted tasks retain their submission-time pricing snapshot. Do not add a 1.4 multiplier in your client, multiply per-task prices by seconds, or apply another exchange-rate conversion. No paid generation was used to verify this documentation update.

Video artifact metadata may include `storage` (`pending_copy`, `local`, or `expired`) and `expires_at` (Unix seconds). Only `local` confirms a server copy. Retention is 24 hours from task completion, not from download or copying; the server copies original bytes without re-encoding. Pending or unknown storage does not prove delivery. Download promptly; expired content returns HTTP 410. A browser asset copy does not extend server retention.

One-click setup creates group-scoped keys that follow the group's enabled models. This does not remove IP, expiry, quota or model restrictions from manually configured keys, and does not grant access to another group.

MiniMax CF models require an image and use a super-resolution route; "4K" does not mean native 4K generation. Use `requires_image`, `sizes` and other live fields instead of inferring behavior from a model's name.

## 5. Discover video capabilities and the RM quote

```bash
curl --fail-with-body --max-time 60 "$KEY711_BASE_URL/v1/video/models" \
  -H "Authorization: Bearer $KEY711_API_KEY"
```

The response has an `object: "list"` wrapper with a `data` array. Model entries include:

| Field | Meaning |
| --- | --- |
| `id`, `group` | Exact model and selected key group |
| `resolution` | Model's fixed output tier |
| `resolutions` | Allowed resolution choices, if more than one is available |
| `durations_seconds` | Allowed integer durations |
| `ratios` | Allowed aspect ratios |
| `sizes` | Ratio-to-size mapping, where applicable |
| `max_images`, `max_videos`, `max_audios` | Reference-count limits |
| `max_video_duration_seconds` | Reference-video duration cap, if supplied |
| `max_audio_duration_seconds` | Reference-audio duration cap, if supplied |
| `max_video_size_bytes`, `max_audio_size_bytes` | Per-file upload limits |
| `min_prompt_length`, `max_prompt_length` | Prompt length limits, when supplied |
| `max_references`, `max_audio_video_references` | Additional combined reference-count limits, when supplied |
| `max_reference_duration_seconds` | Sum of reference-video and reference-audio durations, when supplied |
| `requires_image` | Whether a reference image is mandatory |
| `supports_first_last_frame` | Whether first/last-frame mode is supported |
| `input_mode` | `text_only` or `text_and_image` |
| `price.currency` | `RM` |
| `price.mode` | `per_second`, `per_task` or `variable` |
| `price.unit_amount` | Unit price when available |
| `price.totals` | Entries of `{ "seconds": 4, "total": 0.16 }`, for example |
| `price.by_resolution` | Quotes keyed by an allowed resolution, each with its own unit price and duration totals |

For **seedance W-zq**, the administrator-confirmed prompt limit is **7,000 Unicode characters**, not the gateway-wide 15,000-character protection ceiling. Count the final prompt after reference aliases are compiled. Creator and canvas use the matching key's `max_prompt_length`; API clients must refresh capabilities before submission. Over-limit prompts are rejected before upstream submission, never silently truncated. Other providers keep their own limits.

Use the matching **`price.by_resolution[resolution].totals`** entry for multi-resolution models, or **`price.totals`** for a fixed-resolution model. Do not multiply a per-task price by seconds, infer prices from a model name, or apply the WordPress currency conversion. Group multipliers and server billing rules are already reflected in the quote.

Use the server's total for the exact selected resolution and duration rather than copying an illustrative price into client code. Confirm the live quote before submitting. Waiting or polling time is not the generated video duration.

Capability data depends on authorized upstream metadata and route readiness. A model listed on the pricing page or generic `/v1/models` may still be unavailable for video submission. The gateway rejects unavailable or mismatched capabilities instead of guessing.

## 6. Create, poll and download a video

Creator and these submission examples allow up to 300 seconds for a create response, with no automatic POST retry. Cancellation signals remain active. Upload and status-query timeouts are separate. An error may include `task_id` under `error` or `data` for an UNKNOWN audit record: keep that ID and reconcile logs and balance before another submission. It is not confirmation that the upstream accepted a generation task.

### Create

First confirm this model, duration and ratio are present in the live response:

```bash
curl --fail-with-body --connect-timeout 30 --max-time 300 \
  "$KEY711_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $KEY711_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-h3-quantized-768p",
    "prompt": "A slow camera move around a green bottle in soft studio lighting.",
    "seconds": 4,
    "aspect_ratio": "16:9"
  }'
```

KEY711 accepts JSON on this video route. The video plugin does not expose the upstream multipart-create workflow. `seconds` must be a JSON integer, not a quoted string. Apply the returned prompt limits (legacy routes default to a 5,000-character maximum). Choose `resolution` from `resolutions` when supported; otherwise the tier is fixed by the model. Omit `size` so the server derives it correctly. For MiniMax CF, the derived value is uppercase `2K` or `4K`, not arbitrary width/height.

An illustrative create response:

```json
{
  "id": "<KEY711_VIDEO_ID>",
  "object": "video",
  "model": "minimax-h3-quantized-768p",
  "status": "queued"
}
```

Save **`id`**. KEY711 replaces the upstream identity with its own public task ID and removes `task_id`. Do not build requests using an upstream internal ID.

### Poll

```bash
VIDEO_ID='<ID_FROM_CREATE_RESPONSE>'
curl --fail-with-body --max-time 60 "$KEY711_BASE_URL/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $KEY711_API_KEY"
```

Poll every 10-30 seconds:

- `queued` or `in_progress`: keep waiting on the same task.
- `completed`: download the result.
- `failed`: inspect the error and task/usage logs before deciding on a new request.
- `unknown`: continue checking the existing task and contact support when needed; do not automatically resubmit.

An HTTP 200 from the status endpoint only means the record was read successfully. Inspect `status`. A client timeout does not cancel the job. Repeating a create request can create a new billable task; the upstream image-batch idempotency guarantee does not apply here.

### Download

```bash
curl --fail-with-body --max-time 600 \
  "$KEY711_BASE_URL/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $KEY711_API_KEY" \
  --output video.mp4
```

Use the same authorized key/account. Do not substitute the upstream `/v1/videos/public/{id}` path. Do not forward your key to a third-party media URL. Verify a successful HTTP response before treating a downloaded file as MP4.

## 7. Video reference images and advanced inputs

### Upload an image

```bash
curl --fail-with-body --max-time 120 \
  "$KEY711_BASE_URL/v1/video/reference-images" \
  -H "Authorization: Bearer $KEY711_API_KEY" \
  -F 'model=minimax-h3-original-cf-2k' \
  -F 'file=@reference.png'
```

The response contains `url`. Copy it unchanged. KEY711 either forwards the upload to the chosen channel or stores a temporary signed reference for that channel to read. Do not replace it with a localhost path or remove its query string. The limit is one PNG/JPEG/WebP file per upload, no more than 10 MiB or 40 million pixels. Repeat uploads for additional reference images within `max_images` and any combined limits. Expired references must be uploaded again.

Then submit a JSON video request:

```json
{
  "model": "minimax-h3-original-cf-2k",
  "prompt": "Keep the bottle design and slowly move the camera around it.",
  "seconds": 4,
  "aspect_ratio": "16:9",
  "images": ["<URL_RETURNED_BY_KEY711_UPLOAD>"]
}
```

Do not submit arbitrary remote images, data URLs, base64 or local file paths to the video `images` array. The current video gateway validates provider-specific media locations. The ordinary image-edit endpoint has different input rules.

### Video and audio references

The video decoder accepts `reference_videos` / `reference_audios` arrays (and supported `videos` / `audios` aliases), subject to live capability limits and accepted provider media URLs. Do not send both aliases for one media type. Do not use singular `reference_video`, `reference_audio` or `image` fields.

Upload video or audio to **`POST /v1/video/reference-media`**, with the same bearer header and multipart `model` and `file` fields as image uploads, plus `type=videos` or `type=audios`. Use the returned URLs in the matching arrays. Upload limits are at most 50 MiB per video and 30 MiB per audio, or the model's tighter live limit. Validate individual and combined counts and durations before submitting. For mixed references on the `minimax-h3-*` routes, at least one image is required. The quantized H3 route accepts no video/audio references. The W-zq model ID `H3` has its separate live reference contract described above.

### First and last frames

Only use these modes when `supports_first_last_frame` is true for the selected model:

- MiniMax H3 (non-quantized): `workflow_id: "fl2v"` with one or two uploaded URLs in `images`; do not include video/audio references in this mode.
- Supported Seedance routes: `input_reference` for the first frame and optional `image_end` for the last frame. Do not combine `input_reference` with `images`.

Do not infer first/last-frame support from a model's marketing name.

## 8. Server-side JavaScript / TypeScript

Node.js 20+ example. Keep this code on your backend, not in a public browser application:

```javascript
const base = process.env.KEY711_BASE_URL.replace(/\/$/, "");
const key = process.env.KEY711_API_KEY;
if (!key) throw new Error("Set KEY711_API_KEY");

const response = await fetch(base + "/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "minimax-h3-quantized-768p",
    prompt: "A green bottle turning slowly under soft studio lighting.",
    seconds: 4,
    aspect_ratio: "16:9",
  }),
  signal: AbortSignal.timeout(300000),
});
if (!response.ok) throw new Error(await response.text());
const task = await response.json();
console.log(task.id); // Persist this ID, then poll the same task.
```

The same body works in TypeScript. Add application-specific validation for responses; never assume a successful HTTP status guarantees a completed generation.

## 9. Errors, charges and operational safety

| Status / condition | Action |
| --- | --- |
| 400 | Check model, integer seconds, allowed ratio, reference count and required image |
| 401 | Check the KEY711 key and Authorization header |
| 403 | Check key group, model permissions and video route readiness |
| 404 | Check endpoint and task ownership/ID |
| 413 | Reduce image dimensions or request size |
| 429 | Reduce concurrency and back off; do not hammer the gateway |
| 5xx | Check task/usage records before creating another billable request |
| Network timeout | Treat outcome as uncertain, not automatically failed or refunded |
| Video model absent from capabilities | Do not submit until the route and live capabilities are available |

Avoid unlimited automatic retries, especially on create endpoints. Store your own business request ID, KEY711 task ID where returned, timestamps, model, duration and quoted amount. Never store full API keys in these logs.

Video billing may reserve quota and settle or refund during task processing. Failure/refund timing depends on task state; a browser timeout alone does not trigger a guaranteed refund. The wallet and usage records are authoritative. Read-only model/status queries are not new generation tasks, but still observe rate limits.

The catalog's listed routes do not prove every model has completed an end-to-end generation test. Start any newly enabled production model with an explicitly authorized, low-cost request and verify output, task status and RM settlement together.