Edit the CONFIG block at the top (base URL + your API key), then copy the whole prompt and hand it to an AI coding assistant — it contains everything it needs to build the Android integration. The bottom of this page is a manual reference if you'd rather write it yourself.

# API_Gateway · spec version {{GATEWAY_VERSION}} · last updated {{SPEC_UPDATED}}
# TASK
Implement an Android (Kotlin) client for our AI Gateway, following the spec below.

# ===== CONFIG (edit these — kept at the TOP so they're easy to find & change) =====
const val BASE_URL = "{{BASE_URL}}"
const val API_KEY  = "PASTE_YOUR_GATEWAY_API_KEY_HERE"   // sent as: Authorization: Bearer <API_KEY>
// =====================================================================================

# ABOUT THE SYSTEM (read this)
Transport: HTTPS https://api-gateway.wmazing.cloud (recommended); HTTP http://api-gateway.wmazing.cloud is also supported. No forced redirect or HSTS upgrade. Set BASE_URL to either complete URL, without a trailing /v1.

The gateway sits in front of an AI provider. Clients call the gateway, never the
provider directly — provider keys never leave the server. All endpoints live under
BASE_URL + "/v1". Every response carries an X-Request-Id header for tracing. Success bodies (HTTP 2xx) are JSON
{ request_id, result, usage, error:null }; error bodies (HTTP 4xx/5xx) are { error:{ code, message,
request_id } } — there is NO top-level request_id/result/usage on errors, so read the id from
error.request_id or the X-Request-Id header.

# AUTH
Send your key on every call:  Authorization: Bearer <API_KEY>
(Get the key from the gateway console. A 401 means the key is missing, invalid, or expired.)

# ENDPOINTS
POST /v1/chat   { messages:[{role,content}], model?, max_tokens? }   (messages must be non-empty)
                LIVE — the gateway proxies to the AI provider. Success result:
                { type:"text", model, message:{role:"assistant",content}, latency_ms, provider_request_id },
                plus a usage:{prompt_tokens,completion_tokens,total_tokens} block — parse result.message.content.
                model? optional (defaults to the first enabled text model; or pass an id from GET /v1/models).
                max_tokens? is VALIDATED against the model's own max_output_tokens, not clamped (default
                  1024). Above the ceiling you get 400 naming it, plus max_tokens_suggested. Read the
                  ceiling from GET /v1/models; the reply echoes what was applied in
                  result.limits.max_tokens_applied. A conversation longer than the model's context window
                  is refused with 413 before any provider call is spent.
                "stream": true IS SUPPORTED — see "# STREAMING" below. Streaming is the right answer for
                  anything longer than a short reply: it is not subject to the buffered generation wall.
                timeout_ms? optional — YOUR window, in milliseconds. Clamped to the model's ceiling: you may
                  ask for less, never more. The window actually in force comes back as
                  result.limits.timeout_ms (and in the SSE `start` event, BEFORE the first token), with
                  timeout_source (measured|default) and timeout_clamped so you are never silently given a
                  different deal than you asked for.
# --- Image understanding / 看圖答問 (LIVE) — image in, TEXT out ---
POST /v1/img2txt   { image | images:[...], prompt, model?, image_mime?, max_tokens?, timeout_ms? }
                image = base64 or a data: URL of ONE photo; images = an array (max 8) to ask about several
                at once. prompt = the QUESTION about the picture ("How many people are in this image?").
                This is a TEXT call that happens to take a picture: it resolves from the TEXT model catalog,
                is billed per token, and returns a message — never an image. model? must be a VISION-capable
                text model THAT THIS GATEWAY HAS ENABLED for it; discover them with
                GET /v1/models?vision=1, which lists exactly those (each entry carries
                capabilities.vision = the model can read images, and capabilities.img2txt = this gateway
                accepts image questions on it; you need the second). Omit model? and the gateway picks the
                first enabled one. A model that is not enabled — or cannot see at all — is refused 400
                rather than silently answering from the prompt alone, which is what several providers
                themselves do and the reason the check lives here instead of at the vendor.
                Success result: { type:"text", ai_type:"text.img2txt", model, message:{role,content},
                image_count, latency_ms, provider_request_id, limits } — read message.content for the answer.
                No streaming on this route: the whole wait is the model LOOKING at the picture, which a
                stream cannot make visible. Bodies allow up to 64 MB, like the image routes.
# --- Image generation (LIVE — gateway holds the provider credential) ---
# TIMING: image windows are PER MODEL AND PER CAPABILITY, and they are wide. Measured:
#   qwen-image-2.0-pro  12s with no source photo, 20s with one, 279s with two.
#   gpt-image-2         ~25-30s typically, but 60s has been seen on the same request.
# So do NOT assume ~10s and do NOT set a short client-side HTTP timeout: budget minutes
# for multi_image2image. Every image reply carries result.limits — timeout_ms (the window
# actually applied), timeout_source, timeout_clamped, buffered_strategy — so you can show a
# realistic progress expectation instead of guessing. Send timeout_ms to ask for a SHORTER
# window than the model's; you can never ask for a longer one, and if you try, the reply
# says so via timeout_clamped:true. buffered_strategy is "direct" or "via_stream": on
# via_stream the gateway is consuming the provider's own image stream on your behalf and
# judging the call by silence, which is why those models no longer time out.
POST /v1/txt2image          { prompt, model?, size?, timeout_ms? }         no source image.
POST /v1/image2image        { image, prompt, model?, image_mime?, size?, timeout_ms? }
                                                                          image = base64 or data: URL of ONE source photo.
POST /v1/multi_image2image  { images:[...], prompt, model?, size?, timeout_ms? }
                                                                          images = non-empty array of base64/data-URL photos (max 16).
                model? defaults to qwen-image-2.0 (handles all three). One gateway key authenticates every
                route (auth is per-user). Success result: { type:"image", ai_type, model,
                images:[{url}|{b64,mime}], latency_ms, provider_request_id }. Qwen returns a SIGNED URL that
                expires in ~24h — fetch/cache promptly, don't persist it. A model must be
                enabled for the capability or you get 400 VALIDATION_ERROR "Model … is not enabled for <cap>".
                Image bodies allow up to 64 MB (vs 256 KB JSON); nginx caps the body too — keep images small.
                size? IS OPTIONAL AND THE RULES ARE THE VENDOR'S — the gateway forwards your value unchanged and
                validates nothing. Omitting it (vendor default) is safest. If you send it: "WIDTHxHEIGHT", lower-case
                x, e.g. "1024x1024". NOT "width*height", NOT "2k", NOT "1:3". Per vendor:
                  openai  gpt-image-…      both dimensions divisible by 16, and not below the model's min pixel budget.
                  ark     doubao-seedream- at least 3,686,400 px total (1536x2048 = 3,145,728 is REFUSED); 1k/2k/4k ok.
                  qwen    qwen-image-…     send "WIDTHxHEIGHT" too — the gateway rewrites it to DashScope's
                                           "width*height". It is the ONLY vendor it rewrites for, so a "*" copied
                                           from DashScope docs fails on every other model here.
                A bad size returns 400 VALIDATION_ERROR carrying the VENDOR'S OWN sentence in error.message
                (e.g. "image size must be at least 3686400 pixels"). Read it and change the value — retrying the
                same size returns the same 400 and still spends a request from the quota.
GET  /v1/usage  -> caller's month-to-date usage + plan limit
GET  /v1/image-models -> the IMAGE models this gateway offers. /v1/models is TEXT ONLY and never lists an
                image model, so this is the ONLY way to discover them; use a returned id as the "model" for
                /v1/txt2image, /v1/image2image and /v1/multi_image2image. Each entry carries capabilities
                {txt2image, img2image, multi_image} saying which of those three routes it is valid for, plus
                max_images (the multi_image2image reference cap) and servable.
                servable:false means DO NOT OFFER IT — either the gateway holds no key for that vendor, or the
                vendor permanently refused the model on the last real call (unservable_reason tells you which:
                no_provider_key | vendor_refused; last_status/last_at are the evidence). A vendor can refuse a
                model the gateway has correctly enabled — e.g. an Ark account that has not activated it — and
                no gateway setting fixes that. Use GET /v1/image-models?servable=1 so your picker never offers
                one that cannot run; result.unservable counts what was left out.
GET  /v1/models -> models this gateway offers; use a returned id as /v1/chat's "model" (one key works for all).
                Each entry carries timeout_ms (the window that model gets for ONE buffered generation — set
                per model from measurement, not a flat default), timeout_source and stream_recommended.
                READ THE WINDOW BEFORE THE CONVERSATION STARTS so both sides agree what "too long" means.
                Each entry carries max_input_tokens / max_output_tokens / limits_verified — read those
                instead of guessing — plus `configured` (false = the gateway holds no active key for that
                vendor, so the model is listed but answers 503 PROVIDER_NOT_CONFIGURED) and the measured
                tokens_per_sec / max_tokens_suggested (null = never measured, NOT unlimited).
                Use GET /v1/models?configured=1 to list only models that will actually run;
                result.unconfigured counts what was filtered out. Build your picker from that.
GET  /health    -> liveness (no auth)

# ERRORS (read HTTP status + error.code, log request_id)
400/413 VALIDATION_ERROR · 401 AUTH_REQUIRED / AUTH_INVALID (key missing/invalid/expired) ·
429 RATE_LIMITED / QUOTA_EXCEEDED (honour Retry-After, back off with jitter) ·
503 PROVIDER_TIMEOUT / PROVIDER_NOT_CONFIGURED / PROVIDER_ERROR (see the fault table below).

# WHICH OF THE THREE PARTIES STOPPED?
Provider, gateway, client — any of them can end a call, and they need different responses:
  503 PROVIDER_TIMEOUT (JSON body, retriable:false, carries timeout_ms + stream_recommended)
      THE GATEWAY gave up at its window. The message names the fix. Never a silent hang.
  504 with no JSON body
      THE REVERSE PROXY, not the gateway — your requested window outran the proxy's own limit.
      Lower timeout_ms, or stream.
  stream ends with no `done` and no `error` event
      THE CLIENT or the network dropped it. Every gateway-side ending is explicit: exactly one
      `done` or one `error` always precedes `data: [DONE]`.

# CONTENT IS PASSED THROUGH WHOLE
The gateway does not trim, summarise or re-encode provider replies on either path. Verified by
requesting a 250-line ordered sequence and checking every line survived: buffered and streamed
produced identical content, and what the gateway stored matched what it delivered. Assemble deltas
by simple concatenation — they are raw fragments, not sentences, and a token may split mid-word.

# LONG-GENERATION MODELS (served by copying the provider's method)
A few models cannot be served by an ordinary buffered request AT ANY TIMEOUT: they think for tens of
seconds before emitting, so the gateway holds a silent socket and cannot tell working from dead.
For those, the gateway asks the vendor for a STREAM even when you sent stream:false, consumes it
server-side, and returns the assembled answer in the normal envelope. Bytes flow, so the call is
bounded by SILENCE rather than elapsed time.
  · Your code does not change — same request, same response shape.
  · result.limits.buffered_strategy tells you which path ran: "direct" or "via_stream".
  · GET /v1/models publishes it per model, so a picker can show it up front.
Measured on grok-4.6: a 30s window fails; the model's own strategy returns 4,361 chars in 57s.
Per model only — a direct call stays simpler wherever the ordinary window already fits.

# SHORT VS LONG — DIFFERENT HANDLING
Short reply  -> buffered is fine: one request, one JSON response, simplest to write.
Long reply   -> stream it. Buffered, the whole cost lands inside one window and the user sees
                nothing until it ends; streamed, the first token usually arrives under a second and
                the window only ever measures SILENCE.
The dividing line is per model, and the gateway gives you the numbers: max_tokens_suggested for the
budget, stream_recommended for the verdict (it is also set per-CALL when your max_tokens exceeds
what that model was measured to finish in time).

# PROVIDER FAULTS — BRANCH ON error.retriable, NOT ON THE MESSAGE TEXT
Every 503 carries a code and a boolean, so you never have to string-match English prose:
  PROVIDER_TIMEOUT          retriable:false  the gateway abandoned a BUFFERED generation at its 30s wall.
                                             Do not retry unchanged — it times out identically. Retry
                                             smaller (halve max_tokens), or switch to "stream": true.
  PROVIDER_NOT_CONFIGURED   retriable:false  no active provider key for that vendor (the error carries
                                             `vendor`). Permanent until an operator acts. Pick another
                                             model, or use GET /v1/models?configured=1 in your picker.
  PROVIDER_ERROR            retriable:true   a genuine transient upstream fault: retry 1–2× with
                                             backoff + jitter.
Treating every 503 as retriable costs three 30s failures — 90+ seconds — before the user sees anything,
and none of those retries can succeed.

# STREAMING — THE ANSWER TO LONG REPLIES
Send "stream": true and the 30s generation wall stops applying. The response is text/event-stream:

    event: start
    data: {"request_id":"req_…","model":"…","limits":{…}}

    event: delta
    data: {"text":"Cache-Control"}

    event: done
    data: {"usage":{…},"limits":{…},"latency_ms":46013}

    data: [DONE]

Exactly one `done` OR one `error` always arrives before `data: [DONE]`, so you never have to guess how the
stream ended. An `error` event carries code, retriable and partial_chars — a stream that dies mid-answer
still delivered real text, and you can keep it. Parse deltas incrementally; do not wait for the whole body.

Why this removes the wall: a buffered call must guess a timeout, because until the response lands it
cannot tell a slow model from a dead one. A stream can tell — tokens are either arriving or they are not —
so it is bounded by SILENCE (30s with no data), not by total length.

Measured here on 2026-08-17, two distinct wins:
  - IT REMOVES THE WALL. grok-4.6 at just max_tokens 512 fails buffered with 503 PROVIDER_TIMEOUT,
    because it spends 18.2 s reasoning before its first token; streamed, the same call finishes in
    18.9 s. Thinking time blew the budget, not output length.
  - IT REMOVES THE WAIT. claude-sonnet-5 at max_tokens 2500 does complete buffered, in 24.8 s — but
    with ~5 s of headroom and nothing shown to the user for 25 s. Streamed, the first token lands at
    3.5 s.
Streaming costs the same and is logged the same.

# IF YOU CANNOT STREAM — SIZING max_tokens FOR A BUFFERED CALL
BUFFERED GENERATIONS ARE STILL ABANDONED AT 30 SECONDS. A model writes until it finishes or hits
max_tokens, so max_tokens sets the worst-case output LENGTH and therefore the worst-case TIME. Against a
fixed 30s wall it is a time budget wearing a token label, so the safe value is per MODEL, not per API:

        safe max_tokens  ≈  (that model's tokens/sec) × 25        [25s, leaving margin]

The old trap, now half-closed: the gateway used to CLAMP an oversized max_tokens and carry on, so probing
for the largest accepted value returned the WRONG ceiling. It now REJECTS with 400 and hands back
max_output_tokens and max_tokens_suggested. What it still cannot do is check whether an in-range budget
will FINISH inside 30s — which is what max_tokens_suggested is for, and why streaming is the better answer.

Measured on this gateway, 2026-08-16, ~5,600-token prompts, non-streaming. These move as providers and
hardware change — treat them as a starting point and record your own:

    model                        tok/s   fits in one 30s call   notes
    claude-haiku-4-5             ~120    ~3,600
    deepseek-v4-pro              ~100    ~3,000
    deepseek-v4-flash             ~95    ~2,800
    doubao-seed-2-0-mini-260215   ~90    ~2,500
    gpt-5.6-terra                 ~90    ~2,500                 borderline at 4,096
    qwen3.5-flash                 ~85    ~2,000                 times out at 4,096

REASONING MODELS ARE ABSENT FROM THIS TABLE ON PURPOSE. claude-opus-5, claude-sonnet-5,
claude-fable-5, qwen3.8-max and grok-4.6 report tokens_per_sec: null because a rate does not
describe them — their cost is a large fixed thinking period plus a fast tail. grok-4.6 spent
18.2 s before its first token and then emitted 35 tokens, which computes to 2 tok/s and a "safe"
budget of zero. STREAM these models instead of sizing a buffered budget: a buffered grok-4.6 call
at 512 tokens returns 503 PROVIDER_TIMEOUT.

If you need MORE output than one buffered call can hold, stream it. If you genuinely cannot, the fallback
is to CONTINUE, not enlarge:
1. Ask for a safe max_tokens. If usage.completion_tokens comes back AT the budget the answer was cut off,
   so send [original prompt, assistant: text-so-far, "continue from exactly where you stopped"] and
   concatenate. Each part is its own sub-30s call.
2. Continuations get SLOWER, because each one re-sends everything written so far. Expect part N to run
   nearer the wall than part 1, and keep the finished parts when one fails.
3. On a timeout, HALVE that model's max_tokens and REMEMBER IT. There is rarely room to fail at 30s and
   then succeed within the same request; the value of a failure is what it teaches the next request.
4. Raise a learned-down budget only when a model's slowest call used well under the window (<70%). Part
   count alone is not evidence of headroom.
5. DO NOT hold one HTTP connection open for the whole thing. Behind a proxy (nginx defaults to a 60s read
   timeout) a multi-call answer returns an opaque 504 — the gateway calls are legal, the transport is not.
   Run generation as a background job and let the client poll.

# RATE LIMITS (per plan; tunable server-side)
free 30/min, 1,000/mo · pro 120/min, 100,000/mo · admin 600/min, unlimited.

# WHAT TO BUILD
Using OkHttp + Kotlin coroutines (no other heavy deps), produce one file that:
1. Keeps the CONFIG block above at the very TOP so BASE_URL / API_KEY are easy to change.
2. chat(messages): POST BASE_URL + "/v1/chat" with header Authorization: Bearer API_KEY and a JSON
   body { messages:[{role,content}] }; return result, or surface error.code + request_id.
3. Handle 200 ok · 401 (key invalid/expired) · 429 (honour Retry-After, back off) ·
   503 (PROVIDER_TIMEOUT / PROVIDER_NOT_CONFIGURED / PROVIDER_ERROR — branch on error.retriable; only the
       last of the three is worth retrying).
4. A short demo calling chat(listOf(mapOf("role" to "user", "content" to "Hello"))).
Inject API_KEY at build/runtime; don't commit it to source control.

# Video integration — Stages 1–4 (GA00.0.19.142, 2026-10-14)

This current contract supersedes earlier Mini-only / unavailable-stage descriptions. Discover permitted models and modes at runtime; provider activation alone does not enable a gateway capability.

| Model ID | Available client modes | Estimated USD / million output tokens |
| :--- | :--- | ---: |
| dreamina-seedance-2-0-mini-260615 | txt2vid, imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 3.50 |
| dreamina-seedance-2-5-260628 | imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 10.70 at 480p/720p; 11.70 at 1080p |

# Routes and authentication

All four endpoints use Authorization: Bearer <gateway key>. Provider keys remain on the server. The same issued gateway key can be reused across video modes only when the corresponding active BytePlus video.<mode> credential and any explicit provider mapping permit it. Separate app settings do not require newly issued keys.

| Method | Path | Result |
| :--- | :--- | :--- |
| GET | /v1/video/models | result.models[]: id, vendor, modes, resolution, supported_resolutions, enabled_resolutions, duration_seconds, price_usd_per_m_completion_tokens; empty when no permitted credential exists |
| POST | /v1/video/tasks | Persist one UUID client_token before sending; 202 accepted, duplicate UUID returns saved task at 200 |
| GET | /v1/video/tasks/{request_id} | Refresh an owned task; 200 contains state, not proof of completion |
| GET | /v1/video/tasks?client_token=UUID | Recover saved task without another provider submission; 404 if absent |

Responses use {request_id, result, usage:null, error:null}; the top-level request_id identifies the HTTP request, while result.request_id identifies the saved generation task. Save the latter for polling. Another user's task returns 404.

# Submission and ordered references

POST JSON: {client_token:UUID, model, mode, prompt, resolution:"480p"|"720p"|"1080p", duration:5, images:[]}. A prompt of 1–4000 characters is required. supported_resolutions and enabled_resolutions list Mini 480p/720p and Seedance 2.5 480p/720p/1080p. Submit only an enabled resolution for the selected model; 1080p is 2.5-only. Whole-second duration is Mini 4–15 or 2.5 4–30; audio is off. txt2vid uses 16:9, image modes use adaptive ratio. Administrators can review recorded model/resolution usage at /video-analyst.html; it is not a public client API.

| Mode | images[] count and order | Provider roles assigned by gateway |
| :--- | :--- | :--- |
| txt2vid | 0 (omit or []) | none |
| imgf_txt2vid | 1: first frame | first_frame |
| imgfl_txt2vid | 2: first frame, then last frame | first_frame, last_frame |
| imgrs_txt2vid | exactly 2: reference 1, then reference 2 | reference_image, reference_image |

Each image is an original JPEG/PNG/WebP base64 data URL, no remote URL; the encoded URL must be at most 8,000,000 characters (keep original bytes below 5.9 MB). The app JSON ceiling is 16 MiB, but live nginx limits this public video route to 5 MiB total JSON (verified 2026-10-13). Keep the entire base64-expanded request below 5 MiB; this is a combined-body limit, not a per-image allowance. Do not reorder, crop or re-encode reference files silently. Clients send images[], not the provider's content/role schema. A reference image guides content, not a fixed first/last frame. Real-person inputs may be rejected by provider policy. Correct submission is not proof of visual adherence: compare actual sampled first/last frames separately; preserve failures in reports.

# Asynchronous status, recovery and downloads

Persist the immutable draft and UUID before POST. Poll the saved task approximately every 5 seconds while active, slowing down after failures or backgrounding. A provider POST has a 45-second submission timeout and status fetch a 20-second timeout; neither is the video render duration. Allow HTTP overhead (e.g. 60s submit / 30s status), then recover by UUID after a connection failure. Never automatically replace the token or resubmit an uncertain/rejected task. A 404 recovery is not permission for an automatic paid retry: ask the operator to review first. Idempotency-Key is not the video's duplicate mechanism; client_token is.

Read result.state even on HTTP 200: succeeded is the only successful terminal state; failed, cancelled, expired, rejected and submit_unknown stop automatic polling and require visible error/review. A rejected or uncertain submission can be returned as a saved task at HTTP 200. Validate result.output_url before playback/download; success without a usable URL is not a playable-video pass. Treat output URLs as temporary and download promptly. Use the UI labels Refresh video status and Download video from server. Keep references and signed URLs out of public logs.

# Tokens, response time and billing

result includes request_id, provider_task_id, model, mode, state, provider_status, completion_tokens, estimated_cost_usd, output_url, error_code, error_message, created_at, updated_at. Missing values are null, never invented zero. Input tokens and pure queue/render time are not published. Record client-observed end-to-end time separately from submit HTTP time; polling time is not provider render time.

cost_basis remains "estimated" and provider_confirmed_cost_usd remains null on this client API, even when a separate finance observation exists. Estimate = completion_tokens × selected-model rate / 1,000,000 (rounded to six decimals). For example, 48,437 Seedance 2.5 output tokens estimate US$0.518276. Polling and UUID reuse do not create a second generation charge/monthly generation-quota entry; normal authentication and transport errors still apply. Provider gross cost, plan deduction, cash payable and remaining balance are separate facts. A plan-covered charge is not a zero-cost generation. Confirm actual charges in the provider console with evidence; do not automatically mark the ledger confirmed.

# Platform handling

Android: persist draft/token before OkHttp POST; resume polling from stored result.request_id after process restart. iOS: persist draft/token before URLSession POST; keep the gateway key in Keychain, preserve original picker bytes, resume status after relaunch, download via URLSession for Save/Share. Web: keep privileged keys server-side in a backend-for-frontend, not a public bundle/localStorage; a controlled test bench can accept a short-lived restricted key in memory. Both HTTP and HTTPS gateway URLs are supported; HTTPS web pages must use the HTTPS URL to avoid mixed content. cURL: load the key from an environment variable and JSON from a file; retain the UUID and returned result.request_id, never use automatic POST retries.

# Verified test boundaries

Existing simulator reports are evidence, not a new test run: Mini first/last fidelity failures remain failures despite valid wire roles; Seedance 2.5 sampled endpoint composition passed with qualifications, not pixel identity or every-object motion. Reference-mode real-person rejection and the successful illustrated-reference retest remain separate cases. Full 2.0/Fast provider tests do not imply those models are exposed to public clients. No TestFlight or device-validation claim is made by this guide update.


# DEV LOG (required — we use this to improve the spec)
This spec is still evolving and the author cannot see your environment or where the spec was
unclear, so your log is the only feedback channel. Keep a DEV_LOG.md and deliver it with the code.
Purpose: capture real integration experience so the spec can be corrected and clarified.
Record at minimum:
- Build platform: OS + version, IDE / build tools + versions, language / SDK / runtime versions.
- Target / deployment platform: device or emulator + OS version.
- Tools used: AI assistant + model, libraries + versions, anything else.
- What failed and how you solved it — or could NOT solve, and why.
- Anything in the spec that was missing, ambiguous, wrong, or that you had to assume.
- MEASURED NUMBERS, not just prose: observed tokens/sec per model you used, the largest max_tokens each
  one completed reliably, and any request that timed out (with its prompt size). Those three facts build
  the table in "# LONG ANSWERS", they change as providers and hardware change, and nobody can supply them
  from the server side.
- Any other detail that would help the next developer or improve the spec.

Edit the CONFIG block at the top (base URL + your API key), then copy the whole prompt and hand it to an AI coding assistant — it contains everything it needs to build the iOS integration. The bottom of this page is a manual reference if you'd rather write it yourself.

# API_Gateway · spec version {{GATEWAY_VERSION}} · last updated {{SPEC_UPDATED}}
# TASK
Implement an iOS (Swift) client for our AI Gateway, following the spec below.

# ===== CONFIG (edit these — kept at the TOP so they're easy to find & change) =====
let BASE_URL = "{{BASE_URL}}"
let API_KEY  = "PASTE_YOUR_GATEWAY_API_KEY_HERE"   // sent as: Authorization: Bearer <API_KEY>
// =====================================================================================

# ABOUT THE SYSTEM (read this)
Transport: HTTPS https://api-gateway.wmazing.cloud (recommended); HTTP http://api-gateway.wmazing.cloud is also supported. No forced redirect or HSTS upgrade. Set BASE_URL to either complete URL, without a trailing /v1.

The gateway sits in front of an AI provider. Clients call the gateway, never the
provider directly — provider keys never leave the server. All endpoints live under
BASE_URL + "/v1". Every response carries an X-Request-Id header for tracing. Success bodies (HTTP 2xx) are JSON
{ request_id, result, usage, error:null }; error bodies (HTTP 4xx/5xx) are { error:{ code, message,
request_id } } — there is NO top-level request_id/result/usage on errors, so read the id from
error.request_id or the X-Request-Id header.

# AUTH
Send your key on every call:  Authorization: Bearer <API_KEY>
(Get the key from the gateway console. A 401 means the key is missing, invalid, or expired.)

# ENDPOINTS
POST /v1/chat   { messages:[{role,content}], model?, max_tokens? }   (messages must be non-empty)
                LIVE — the gateway proxies to the AI provider. Success result:
                { type:"text", model, message:{role:"assistant",content}, latency_ms, provider_request_id },
                plus a usage:{prompt_tokens,completion_tokens,total_tokens} block — parse result.message.content.
                model? optional (defaults to the first enabled text model; or pass an id from GET /v1/models).
                max_tokens? is VALIDATED against the model's own max_output_tokens, not clamped (default
                  1024). Above the ceiling you get 400 naming it, plus max_tokens_suggested. Read the
                  ceiling from GET /v1/models; the reply echoes what was applied in
                  result.limits.max_tokens_applied. A conversation longer than the model's context window
                  is refused with 413 before any provider call is spent.
                "stream": true IS SUPPORTED — see "# STREAMING" below. Streaming is the right answer for
                  anything longer than a short reply: it is not subject to the buffered generation wall.
                timeout_ms? optional — YOUR window, in milliseconds. Clamped to the model's ceiling: you may
                  ask for less, never more. The window actually in force comes back as
                  result.limits.timeout_ms (and in the SSE `start` event, BEFORE the first token), with
                  timeout_source (measured|default) and timeout_clamped so you are never silently given a
                  different deal than you asked for.
# --- Image understanding / 看圖答問 (LIVE) — image in, TEXT out ---
POST /v1/img2txt   { image | images:[...], prompt, model?, image_mime?, max_tokens?, timeout_ms? }
                image = base64 or a data: URL of ONE photo; images = an array (max 8) to ask about several
                at once. prompt = the QUESTION about the picture ("How many people are in this image?").
                This is a TEXT call that happens to take a picture: it resolves from the TEXT model catalog,
                is billed per token, and returns a message — never an image. model? must be a VISION-capable
                text model THAT THIS GATEWAY HAS ENABLED for it; discover them with
                GET /v1/models?vision=1, which lists exactly those (each entry carries
                capabilities.vision = the model can read images, and capabilities.img2txt = this gateway
                accepts image questions on it; you need the second). Omit model? and the gateway picks the
                first enabled one. A model that is not enabled — or cannot see at all — is refused 400
                rather than silently answering from the prompt alone, which is what several providers
                themselves do and the reason the check lives here instead of at the vendor.
                Success result: { type:"text", ai_type:"text.img2txt", model, message:{role,content},
                image_count, latency_ms, provider_request_id, limits } — read message.content for the answer.
                No streaming on this route: the whole wait is the model LOOKING at the picture, which a
                stream cannot make visible. Bodies allow up to 64 MB, like the image routes.
# --- Image generation (LIVE — gateway holds the provider credential) ---
# TIMING: image windows are PER MODEL AND PER CAPABILITY, and they are wide. Measured:
#   qwen-image-2.0-pro  12s with no source photo, 20s with one, 279s with two.
#   gpt-image-2         ~25-30s typically, but 60s has been seen on the same request.
# So do NOT assume ~10s and do NOT set a short client-side HTTP timeout: budget minutes
# for multi_image2image. Every image reply carries result.limits — timeout_ms (the window
# actually applied), timeout_source, timeout_clamped, buffered_strategy — so you can show a
# realistic progress expectation instead of guessing. Send timeout_ms to ask for a SHORTER
# window than the model's; you can never ask for a longer one, and if you try, the reply
# says so via timeout_clamped:true. buffered_strategy is "direct" or "via_stream": on
# via_stream the gateway is consuming the provider's own image stream on your behalf and
# judging the call by silence, which is why those models no longer time out.
POST /v1/txt2image          { prompt, model?, size?, timeout_ms? }         no source image.
POST /v1/image2image        { image, prompt, model?, image_mime?, size?, timeout_ms? }
                                                                          image = base64 or data: URL of ONE source photo.
POST /v1/multi_image2image  { images:[...], prompt, model?, size?, timeout_ms? }
                                                                          images = non-empty array of base64/data-URL photos (max 16).
                model? defaults to qwen-image-2.0 (handles all three). One gateway key authenticates every
                route (auth is per-user). Success result: { type:"image", ai_type, model,
                images:[{url}|{b64,mime}], latency_ms, provider_request_id }. Qwen returns a SIGNED URL that
                expires in ~24h — fetch/cache promptly, don't persist it. A model must be
                enabled for the capability or you get 400 VALIDATION_ERROR "Model … is not enabled for <cap>".
                Image bodies allow up to 64 MB (vs 256 KB JSON); nginx caps the body too — keep images small.
                size? IS OPTIONAL AND THE RULES ARE THE VENDOR'S — the gateway forwards your value unchanged and
                validates nothing. Omitting it (vendor default) is safest. If you send it: "WIDTHxHEIGHT", lower-case
                x, e.g. "1024x1024". NOT "width*height", NOT "2k", NOT "1:3". Per vendor:
                  openai  gpt-image-…      both dimensions divisible by 16, and not below the model's min pixel budget.
                  ark     doubao-seedream- at least 3,686,400 px total (1536x2048 = 3,145,728 is REFUSED); 1k/2k/4k ok.
                  qwen    qwen-image-…     send "WIDTHxHEIGHT" too — the gateway rewrites it to DashScope's
                                           "width*height". It is the ONLY vendor it rewrites for, so a "*" copied
                                           from DashScope docs fails on every other model here.
                A bad size returns 400 VALIDATION_ERROR carrying the VENDOR'S OWN sentence in error.message
                (e.g. "image size must be at least 3686400 pixels"). Read it and change the value — retrying the
                same size returns the same 400 and still spends a request from the quota.
GET  /v1/usage  -> caller's month-to-date usage + plan limit
GET  /v1/image-models -> the IMAGE models this gateway offers. /v1/models is TEXT ONLY and never lists an
                image model, so this is the ONLY way to discover them; use a returned id as the "model" for
                /v1/txt2image, /v1/image2image and /v1/multi_image2image. Each entry carries capabilities
                {txt2image, img2image, multi_image} saying which of those three routes it is valid for, plus
                max_images (the multi_image2image reference cap) and servable.
                servable:false means DO NOT OFFER IT — either the gateway holds no key for that vendor, or the
                vendor permanently refused the model on the last real call (unservable_reason tells you which:
                no_provider_key | vendor_refused; last_status/last_at are the evidence). A vendor can refuse a
                model the gateway has correctly enabled — e.g. an Ark account that has not activated it — and
                no gateway setting fixes that. Use GET /v1/image-models?servable=1 so your picker never offers
                one that cannot run; result.unservable counts what was left out.
GET  /v1/models -> models this gateway offers; use a returned id as /v1/chat's "model" (one key works for all).
                Each entry carries timeout_ms (the window that model gets for ONE buffered generation — set
                per model from measurement, not a flat default), timeout_source and stream_recommended.
                READ THE WINDOW BEFORE THE CONVERSATION STARTS so both sides agree what "too long" means.
                Each entry carries max_input_tokens / max_output_tokens / limits_verified — read those
                instead of guessing — plus `configured` (false = the gateway holds no active key for that
                vendor, so the model is listed but answers 503 PROVIDER_NOT_CONFIGURED) and the measured
                tokens_per_sec / max_tokens_suggested (null = never measured, NOT unlimited).
                Use GET /v1/models?configured=1 to list only models that will actually run;
                result.unconfigured counts what was filtered out. Build your picker from that.
GET  /health    -> liveness (no auth)

# ERRORS (read HTTP status + error.code, log request_id)
400/413 VALIDATION_ERROR · 401 AUTH_REQUIRED / AUTH_INVALID (key missing/invalid/expired) ·
429 RATE_LIMITED / QUOTA_EXCEEDED (honour Retry-After, back off with jitter) ·
503 PROVIDER_TIMEOUT / PROVIDER_NOT_CONFIGURED / PROVIDER_ERROR (see the fault table below).

# WHICH OF THE THREE PARTIES STOPPED?
Provider, gateway, client — any of them can end a call, and they need different responses:
  503 PROVIDER_TIMEOUT (JSON body, retriable:false, carries timeout_ms + stream_recommended)
      THE GATEWAY gave up at its window. The message names the fix. Never a silent hang.
  504 with no JSON body
      THE REVERSE PROXY, not the gateway — your requested window outran the proxy's own limit.
      Lower timeout_ms, or stream.
  stream ends with no `done` and no `error` event
      THE CLIENT or the network dropped it. Every gateway-side ending is explicit: exactly one
      `done` or one `error` always precedes `data: [DONE]`.

# CONTENT IS PASSED THROUGH WHOLE
The gateway does not trim, summarise or re-encode provider replies on either path. Verified by
requesting a 250-line ordered sequence and checking every line survived: buffered and streamed
produced identical content, and what the gateway stored matched what it delivered. Assemble deltas
by simple concatenation — they are raw fragments, not sentences, and a token may split mid-word.

# LONG-GENERATION MODELS (served by copying the provider's method)
A few models cannot be served by an ordinary buffered request AT ANY TIMEOUT: they think for tens of
seconds before emitting, so the gateway holds a silent socket and cannot tell working from dead.
For those, the gateway asks the vendor for a STREAM even when you sent stream:false, consumes it
server-side, and returns the assembled answer in the normal envelope. Bytes flow, so the call is
bounded by SILENCE rather than elapsed time.
  · Your code does not change — same request, same response shape.
  · result.limits.buffered_strategy tells you which path ran: "direct" or "via_stream".
  · GET /v1/models publishes it per model, so a picker can show it up front.
Measured on grok-4.6: a 30s window fails; the model's own strategy returns 4,361 chars in 57s.
Per model only — a direct call stays simpler wherever the ordinary window already fits.

# SHORT VS LONG — DIFFERENT HANDLING
Short reply  -> buffered is fine: one request, one JSON response, simplest to write.
Long reply   -> stream it. Buffered, the whole cost lands inside one window and the user sees
                nothing until it ends; streamed, the first token usually arrives under a second and
                the window only ever measures SILENCE.
The dividing line is per model, and the gateway gives you the numbers: max_tokens_suggested for the
budget, stream_recommended for the verdict (it is also set per-CALL when your max_tokens exceeds
what that model was measured to finish in time).

# PROVIDER FAULTS — BRANCH ON error.retriable, NOT ON THE MESSAGE TEXT
Every 503 carries a code and a boolean, so you never have to string-match English prose:
  PROVIDER_TIMEOUT          retriable:false  the gateway abandoned a BUFFERED generation at its 30s wall.
                                             Do not retry unchanged — it times out identically. Retry
                                             smaller (halve max_tokens), or switch to "stream": true.
  PROVIDER_NOT_CONFIGURED   retriable:false  no active provider key for that vendor (the error carries
                                             `vendor`). Permanent until an operator acts. Pick another
                                             model, or use GET /v1/models?configured=1 in your picker.
  PROVIDER_ERROR            retriable:true   a genuine transient upstream fault: retry 1–2× with
                                             backoff + jitter.
Treating every 503 as retriable costs three 30s failures — 90+ seconds — before the user sees anything,
and none of those retries can succeed.

# STREAMING — THE ANSWER TO LONG REPLIES
Send "stream": true and the 30s generation wall stops applying. The response is text/event-stream:

    event: start
    data: {"request_id":"req_…","model":"…","limits":{…}}

    event: delta
    data: {"text":"Cache-Control"}

    event: done
    data: {"usage":{…},"limits":{…},"latency_ms":46013}

    data: [DONE]

Exactly one `done` OR one `error` always arrives before `data: [DONE]`, so you never have to guess how the
stream ended. An `error` event carries code, retriable and partial_chars — a stream that dies mid-answer
still delivered real text, and you can keep it. Parse deltas incrementally; do not wait for the whole body.

Why this removes the wall: a buffered call must guess a timeout, because until the response lands it
cannot tell a slow model from a dead one. A stream can tell — tokens are either arriving or they are not —
so it is bounded by SILENCE (30s with no data), not by total length.

Measured here on 2026-08-17, two distinct wins:
  - IT REMOVES THE WALL. grok-4.6 at just max_tokens 512 fails buffered with 503 PROVIDER_TIMEOUT,
    because it spends 18.2 s reasoning before its first token; streamed, the same call finishes in
    18.9 s. Thinking time blew the budget, not output length.
  - IT REMOVES THE WAIT. claude-sonnet-5 at max_tokens 2500 does complete buffered, in 24.8 s — but
    with ~5 s of headroom and nothing shown to the user for 25 s. Streamed, the first token lands at
    3.5 s.
Streaming costs the same and is logged the same.

# IF YOU CANNOT STREAM — SIZING max_tokens FOR A BUFFERED CALL
BUFFERED GENERATIONS ARE STILL ABANDONED AT 30 SECONDS. A model writes until it finishes or hits
max_tokens, so max_tokens sets the worst-case output LENGTH and therefore the worst-case TIME. Against a
fixed 30s wall it is a time budget wearing a token label, so the safe value is per MODEL, not per API:

        safe max_tokens  ≈  (that model's tokens/sec) × 25        [25s, leaving margin]

The old trap, now half-closed: the gateway used to CLAMP an oversized max_tokens and carry on, so probing
for the largest accepted value returned the WRONG ceiling. It now REJECTS with 400 and hands back
max_output_tokens and max_tokens_suggested. What it still cannot do is check whether an in-range budget
will FINISH inside 30s — which is what max_tokens_suggested is for, and why streaming is the better answer.

Measured on this gateway, 2026-08-16, ~5,600-token prompts, non-streaming. These move as providers and
hardware change — treat them as a starting point and record your own:

    model                        tok/s   fits in one 30s call   notes
    claude-haiku-4-5             ~120    ~3,600
    deepseek-v4-pro              ~100    ~3,000
    deepseek-v4-flash             ~95    ~2,800
    doubao-seed-2-0-mini-260215   ~90    ~2,500
    gpt-5.6-terra                 ~90    ~2,500                 borderline at 4,096
    qwen3.5-flash                 ~85    ~2,000                 times out at 4,096

REASONING MODELS ARE ABSENT FROM THIS TABLE ON PURPOSE. claude-opus-5, claude-sonnet-5,
claude-fable-5, qwen3.8-max and grok-4.6 report tokens_per_sec: null because a rate does not
describe them — their cost is a large fixed thinking period plus a fast tail. grok-4.6 spent
18.2 s before its first token and then emitted 35 tokens, which computes to 2 tok/s and a "safe"
budget of zero. STREAM these models instead of sizing a buffered budget: a buffered grok-4.6 call
at 512 tokens returns 503 PROVIDER_TIMEOUT.

If you need MORE output than one buffered call can hold, stream it. If you genuinely cannot, the fallback
is to CONTINUE, not enlarge:
1. Ask for a safe max_tokens. If usage.completion_tokens comes back AT the budget the answer was cut off,
   so send [original prompt, assistant: text-so-far, "continue from exactly where you stopped"] and
   concatenate. Each part is its own sub-30s call.
2. Continuations get SLOWER, because each one re-sends everything written so far. Expect part N to run
   nearer the wall than part 1, and keep the finished parts when one fails.
3. On a timeout, HALVE that model's max_tokens and REMEMBER IT. There is rarely room to fail at 30s and
   then succeed within the same request; the value of a failure is what it teaches the next request.
4. Raise a learned-down budget only when a model's slowest call used well under the window (<70%). Part
   count alone is not evidence of headroom.
5. DO NOT hold one HTTP connection open for the whole thing. Behind a proxy (nginx defaults to a 60s read
   timeout) a multi-call answer returns an opaque 504 — the gateway calls are legal, the transport is not.
   Run generation as a background job and let the client poll.

# RATE LIMITS (per plan; tunable server-side)
free 30/min, 1,000/mo · pro 120/min, 100,000/mo · admin 600/min, unlimited.

# WHAT TO BUILD
Using async/await URLSession (no third-party dependencies), produce one file that:
1. Keeps the CONFIG block above at the very TOP so BASE_URL / API_KEY are easy to change.
2. chat(messages): POST BASE_URL + "/v1/chat" with header Authorization: Bearer API_KEY and JSON body
   { messages:[{role,content}] }; return result, or surface error.code + request_id.
3. Handle 200 ok · 401 (key invalid/expired) · 429 (honour Retry-After, back off) ·
   503 (PROVIDER_TIMEOUT / PROVIDER_NOT_CONFIGURED / PROVIDER_ERROR — branch on error.retriable; only the
       last of the three is worth retrying).
4. A short demo calling chat([["role": "user", "content": "Hello"]]).
Keep the API key out of source control (inject it; never commit it).

# Video integration — Stages 1–4 (GA00.0.19.142, 2026-10-14)

This current contract supersedes earlier Mini-only / unavailable-stage descriptions. Discover permitted models and modes at runtime; provider activation alone does not enable a gateway capability.

| Model ID | Available client modes | Estimated USD / million output tokens |
| :--- | :--- | ---: |
| dreamina-seedance-2-0-mini-260615 | txt2vid, imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 3.50 |
| dreamina-seedance-2-5-260628 | imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 10.70 at 480p/720p; 11.70 at 1080p |

# Routes and authentication

All four endpoints use Authorization: Bearer <gateway key>. Provider keys remain on the server. The same issued gateway key can be reused across video modes only when the corresponding active BytePlus video.<mode> credential and any explicit provider mapping permit it. Separate app settings do not require newly issued keys.

| Method | Path | Result |
| :--- | :--- | :--- |
| GET | /v1/video/models | result.models[]: id, vendor, modes, resolution, supported_resolutions, enabled_resolutions, duration_seconds, price_usd_per_m_completion_tokens; empty when no permitted credential exists |
| POST | /v1/video/tasks | Persist one UUID client_token before sending; 202 accepted, duplicate UUID returns saved task at 200 |
| GET | /v1/video/tasks/{request_id} | Refresh an owned task; 200 contains state, not proof of completion |
| GET | /v1/video/tasks?client_token=UUID | Recover saved task without another provider submission; 404 if absent |

Responses use {request_id, result, usage:null, error:null}; the top-level request_id identifies the HTTP request, while result.request_id identifies the saved generation task. Save the latter for polling. Another user's task returns 404.

# Submission and ordered references

POST JSON: {client_token:UUID, model, mode, prompt, resolution:"480p"|"720p"|"1080p", duration:5, images:[]}. A prompt of 1–4000 characters is required. supported_resolutions and enabled_resolutions list Mini 480p/720p and Seedance 2.5 480p/720p/1080p. Submit only an enabled resolution for the selected model; 1080p is 2.5-only. Whole-second duration is Mini 4–15 or 2.5 4–30; audio is off. txt2vid uses 16:9, image modes use adaptive ratio. Administrators can review recorded model/resolution usage at /video-analyst.html; it is not a public client API.

| Mode | images[] count and order | Provider roles assigned by gateway |
| :--- | :--- | :--- |
| txt2vid | 0 (omit or []) | none |
| imgf_txt2vid | 1: first frame | first_frame |
| imgfl_txt2vid | 2: first frame, then last frame | first_frame, last_frame |
| imgrs_txt2vid | exactly 2: reference 1, then reference 2 | reference_image, reference_image |

Each image is an original JPEG/PNG/WebP base64 data URL, no remote URL; the encoded URL must be at most 8,000,000 characters (keep original bytes below 5.9 MB). The app JSON ceiling is 16 MiB, but live nginx limits this public video route to 5 MiB total JSON (verified 2026-10-13). Keep the entire base64-expanded request below 5 MiB; this is a combined-body limit, not a per-image allowance. Do not reorder, crop or re-encode reference files silently. Clients send images[], not the provider's content/role schema. A reference image guides content, not a fixed first/last frame. Real-person inputs may be rejected by provider policy. Correct submission is not proof of visual adherence: compare actual sampled first/last frames separately; preserve failures in reports.

# Asynchronous status, recovery and downloads

Persist the immutable draft and UUID before POST. Poll the saved task approximately every 5 seconds while active, slowing down after failures or backgrounding. A provider POST has a 45-second submission timeout and status fetch a 20-second timeout; neither is the video render duration. Allow HTTP overhead (e.g. 60s submit / 30s status), then recover by UUID after a connection failure. Never automatically replace the token or resubmit an uncertain/rejected task. A 404 recovery is not permission for an automatic paid retry: ask the operator to review first. Idempotency-Key is not the video's duplicate mechanism; client_token is.

Read result.state even on HTTP 200: succeeded is the only successful terminal state; failed, cancelled, expired, rejected and submit_unknown stop automatic polling and require visible error/review. A rejected or uncertain submission can be returned as a saved task at HTTP 200. Validate result.output_url before playback/download; success without a usable URL is not a playable-video pass. Treat output URLs as temporary and download promptly. Use the UI labels Refresh video status and Download video from server. Keep references and signed URLs out of public logs.

# Tokens, response time and billing

result includes request_id, provider_task_id, model, mode, state, provider_status, completion_tokens, estimated_cost_usd, output_url, error_code, error_message, created_at, updated_at. Missing values are null, never invented zero. Input tokens and pure queue/render time are not published. Record client-observed end-to-end time separately from submit HTTP time; polling time is not provider render time.

cost_basis remains "estimated" and provider_confirmed_cost_usd remains null on this client API, even when a separate finance observation exists. Estimate = completion_tokens × selected-model rate / 1,000,000 (rounded to six decimals). For example, 48,437 Seedance 2.5 output tokens estimate US$0.518276. Polling and UUID reuse do not create a second generation charge/monthly generation-quota entry; normal authentication and transport errors still apply. Provider gross cost, plan deduction, cash payable and remaining balance are separate facts. A plan-covered charge is not a zero-cost generation. Confirm actual charges in the provider console with evidence; do not automatically mark the ledger confirmed.

# Platform handling

Android: persist draft/token before OkHttp POST; resume polling from stored result.request_id after process restart. iOS: persist draft/token before URLSession POST; keep the gateway key in Keychain, preserve original picker bytes, resume status after relaunch, download via URLSession for Save/Share. Web: keep privileged keys server-side in a backend-for-frontend, not a public bundle/localStorage; a controlled test bench can accept a short-lived restricted key in memory. Both HTTP and HTTPS gateway URLs are supported; HTTPS web pages must use the HTTPS URL to avoid mixed content. cURL: load the key from an environment variable and JSON from a file; retain the UUID and returned result.request_id, never use automatic POST retries.

# Verified test boundaries

Existing simulator reports are evidence, not a new test run: Mini first/last fidelity failures remain failures despite valid wire roles; Seedance 2.5 sampled endpoint composition passed with qualifications, not pixel identity or every-object motion. Reference-mode real-person rejection and the successful illustrated-reference retest remain separate cases. Full 2.0/Fast provider tests do not imply those models are exposed to public clients. No TestFlight or device-validation claim is made by this guide update.


# DEV LOG (required — we use this to improve the spec)
This spec is still evolving and the author cannot see your environment or where the spec was
unclear, so your log is the only feedback channel. Keep a DEV_LOG.md and deliver it with the code.
Purpose: capture real integration experience so the spec can be corrected and clarified.
Record at minimum:
- Build platform: OS + version, IDE / build tools + versions, language / SDK / runtime versions.
- Target / deployment platform: device or simulator + OS version.
- Tools used: AI assistant + model, libraries + versions, anything else.
- What failed and how you solved it — or could NOT solve, and why.
- Anything in the spec that was missing, ambiguous, wrong, or that you had to assume.
- MEASURED NUMBERS, not just prose: observed tokens/sec per model you used, the largest max_tokens each
  one completed reliably, and any request that timed out (with its prompt size). Those three facts build
  the table in "# LONG ANSWERS", they change as providers and hardware change, and nobody can supply them
  from the server side.
- Any other detail that would help the next developer or improve the spec.

Edit the CONFIG block at the top (base URL + your API key), then copy the whole prompt and hand it to an AI coding assistant — it contains everything it needs to build the Web integration. The bottom of this page is a manual reference if you'd rather write it yourself.

# API_Gateway · spec version {{GATEWAY_VERSION}} · last updated {{SPEC_UPDATED}}
# TASK
Implement a Web (JavaScript / TypeScript) client for our AI Gateway, following the spec below.

# ===== CONFIG (edit these — kept at the TOP so they're easy to find & change) =====
const BASE_URL = "{{BASE_URL}}";
const API_KEY  = "PASTE_YOUR_GATEWAY_API_KEY_HERE";   // sent as: Authorization: Bearer <API_KEY>
// =====================================================================================

# ABOUT THE SYSTEM (read this)
Transport: HTTPS https://api-gateway.wmazing.cloud (recommended); HTTP http://api-gateway.wmazing.cloud is also supported. No forced redirect or HSTS upgrade. Set BASE_URL to either complete URL, without a trailing /v1.

The gateway sits in front of an AI provider. Clients call the gateway, never the
provider directly — provider keys never leave the server. All endpoints live under
BASE_URL + "/v1". Every response carries an X-Request-Id header for tracing. Success bodies (HTTP 2xx) are JSON
{ request_id, result, usage, error:null }; error bodies (HTTP 4xx/5xx) are { error:{ code, message,
request_id } } — there is NO top-level request_id/result/usage on errors, so read the id from
error.request_id or the X-Request-Id header.

# AUTH
Send your key on every call:  Authorization: Bearer <API_KEY>
(Get the key from the gateway console. A 401 means the key is missing, invalid, or expired.)

# ENDPOINTS
POST /v1/chat   { messages:[{role,content}], model?, max_tokens? }   (messages must be non-empty)
                LIVE — the gateway proxies to the AI provider. Success result:
                { type:"text", model, message:{role:"assistant",content}, latency_ms, provider_request_id },
                plus a usage:{prompt_tokens,completion_tokens,total_tokens} block — parse result.message.content.
                model? optional (defaults to the first enabled text model; or pass an id from GET /v1/models).
                max_tokens? is VALIDATED against the model's own max_output_tokens, not clamped (default
                  1024). Above the ceiling you get 400 naming it, plus max_tokens_suggested. Read the
                  ceiling from GET /v1/models; the reply echoes what was applied in
                  result.limits.max_tokens_applied. A conversation longer than the model's context window
                  is refused with 413 before any provider call is spent.
                "stream": true IS SUPPORTED — see "# STREAMING" below. Streaming is the right answer for
                  anything longer than a short reply: it is not subject to the buffered generation wall.
                timeout_ms? optional — YOUR window, in milliseconds. Clamped to the model's ceiling: you may
                  ask for less, never more. The window actually in force comes back as
                  result.limits.timeout_ms (and in the SSE `start` event, BEFORE the first token), with
                  timeout_source (measured|default) and timeout_clamped so you are never silently given a
                  different deal than you asked for.
# --- Image understanding / 看圖答問 (LIVE) — image in, TEXT out ---
POST /v1/img2txt   { image | images:[...], prompt, model?, image_mime?, max_tokens?, timeout_ms? }
                image = base64 or a data: URL of ONE photo; images = an array (max 8) to ask about several
                at once. prompt = the QUESTION about the picture ("How many people are in this image?").
                This is a TEXT call that happens to take a picture: it resolves from the TEXT model catalog,
                is billed per token, and returns a message — never an image. model? must be a VISION-capable
                text model THAT THIS GATEWAY HAS ENABLED for it; discover them with
                GET /v1/models?vision=1, which lists exactly those (each entry carries
                capabilities.vision = the model can read images, and capabilities.img2txt = this gateway
                accepts image questions on it; you need the second). Omit model? and the gateway picks the
                first enabled one. A model that is not enabled — or cannot see at all — is refused 400
                rather than silently answering from the prompt alone, which is what several providers
                themselves do and the reason the check lives here instead of at the vendor.
                Success result: { type:"text", ai_type:"text.img2txt", model, message:{role,content},
                image_count, latency_ms, provider_request_id, limits } — read message.content for the answer.
                No streaming on this route: the whole wait is the model LOOKING at the picture, which a
                stream cannot make visible. Bodies allow up to 64 MB, like the image routes.
# --- Image generation (LIVE — gateway holds the provider credential) ---
# TIMING: image windows are PER MODEL AND PER CAPABILITY, and they are wide. Measured:
#   qwen-image-2.0-pro  12s with no source photo, 20s with one, 279s with two.
#   gpt-image-2         ~25-30s typically, but 60s has been seen on the same request.
# So do NOT assume ~10s and do NOT set a short client-side HTTP timeout: budget minutes
# for multi_image2image. Every image reply carries result.limits — timeout_ms (the window
# actually applied), timeout_source, timeout_clamped, buffered_strategy — so you can show a
# realistic progress expectation instead of guessing. Send timeout_ms to ask for a SHORTER
# window than the model's; you can never ask for a longer one, and if you try, the reply
# says so via timeout_clamped:true. buffered_strategy is "direct" or "via_stream": on
# via_stream the gateway is consuming the provider's own image stream on your behalf and
# judging the call by silence, which is why those models no longer time out.
POST /v1/txt2image          { prompt, model?, size?, timeout_ms? }         no source image.
POST /v1/image2image        { image, prompt, model?, image_mime?, size?, timeout_ms? }
                                                                          image = base64 or data: URL of ONE source photo.
POST /v1/multi_image2image  { images:[...], prompt, model?, size?, timeout_ms? }
                                                                          images = non-empty array of base64/data-URL photos (max 16).
                model? defaults to qwen-image-2.0 (handles all three). One gateway key authenticates every
                route (auth is per-user). Success result: { type:"image", ai_type, model,
                images:[{url}|{b64,mime}], latency_ms, provider_request_id }. Qwen returns a SIGNED URL that
                expires in ~24h — fetch/cache promptly, don't persist it. A model must be
                enabled for the capability or you get 400 VALIDATION_ERROR "Model … is not enabled for <cap>".
                Image bodies allow up to 64 MB (vs 256 KB JSON); nginx caps the body too — keep images small.
                size? IS OPTIONAL AND THE RULES ARE THE VENDOR'S — the gateway forwards your value unchanged and
                validates nothing. Omitting it (vendor default) is safest. If you send it: "WIDTHxHEIGHT", lower-case
                x, e.g. "1024x1024". NOT "width*height", NOT "2k", NOT "1:3". Per vendor:
                  openai  gpt-image-…      both dimensions divisible by 16, and not below the model's min pixel budget.
                  ark     doubao-seedream- at least 3,686,400 px total (1536x2048 = 3,145,728 is REFUSED); 1k/2k/4k ok.
                  qwen    qwen-image-…     send "WIDTHxHEIGHT" too — the gateway rewrites it to DashScope's
                                           "width*height". It is the ONLY vendor it rewrites for, so a "*" copied
                                           from DashScope docs fails on every other model here.
                A bad size returns 400 VALIDATION_ERROR carrying the VENDOR'S OWN sentence in error.message
                (e.g. "image size must be at least 3686400 pixels"). Read it and change the value — retrying the
                same size returns the same 400 and still spends a request from the quota.
GET  /v1/usage  -> caller's month-to-date usage + plan limit
GET  /v1/image-models -> the IMAGE models this gateway offers. /v1/models is TEXT ONLY and never lists an
                image model, so this is the ONLY way to discover them; use a returned id as the "model" for
                /v1/txt2image, /v1/image2image and /v1/multi_image2image. Each entry carries capabilities
                {txt2image, img2image, multi_image} saying which of those three routes it is valid for, plus
                max_images (the multi_image2image reference cap) and servable.
                servable:false means DO NOT OFFER IT — either the gateway holds no key for that vendor, or the
                vendor permanently refused the model on the last real call (unservable_reason tells you which:
                no_provider_key | vendor_refused; last_status/last_at are the evidence). A vendor can refuse a
                model the gateway has correctly enabled — e.g. an Ark account that has not activated it — and
                no gateway setting fixes that. Use GET /v1/image-models?servable=1 so your picker never offers
                one that cannot run; result.unservable counts what was left out.
GET  /v1/models -> models this gateway offers; use a returned id as /v1/chat's "model" (one key works for all).
                Each entry carries timeout_ms (the window that model gets for ONE buffered generation — set
                per model from measurement, not a flat default), timeout_source and stream_recommended.
                READ THE WINDOW BEFORE THE CONVERSATION STARTS so both sides agree what "too long" means.
                Each entry carries max_input_tokens / max_output_tokens / limits_verified — read those
                instead of guessing — plus `configured` (false = the gateway holds no active key for that
                vendor, so the model is listed but answers 503 PROVIDER_NOT_CONFIGURED) and the measured
                tokens_per_sec / max_tokens_suggested (null = never measured, NOT unlimited).
                Use GET /v1/models?configured=1 to list only models that will actually run;
                result.unconfigured counts what was filtered out. Build your picker from that.
GET  /health    -> liveness (no auth)

# ERRORS (read HTTP status + error.code, log request_id)
400/413 VALIDATION_ERROR · 401 AUTH_REQUIRED / AUTH_INVALID (key missing/invalid/expired) ·
429 RATE_LIMITED / QUOTA_EXCEEDED (honour Retry-After, back off with jitter) ·
503 PROVIDER_TIMEOUT / PROVIDER_NOT_CONFIGURED / PROVIDER_ERROR (see the fault table below).

# WHICH OF THE THREE PARTIES STOPPED?
Provider, gateway, client — any of them can end a call, and they need different responses:
  503 PROVIDER_TIMEOUT (JSON body, retriable:false, carries timeout_ms + stream_recommended)
      THE GATEWAY gave up at its window. The message names the fix. Never a silent hang.
  504 with no JSON body
      THE REVERSE PROXY, not the gateway — your requested window outran the proxy's own limit.
      Lower timeout_ms, or stream.
  stream ends with no `done` and no `error` event
      THE CLIENT or the network dropped it. Every gateway-side ending is explicit: exactly one
      `done` or one `error` always precedes `data: [DONE]`.

# CONTENT IS PASSED THROUGH WHOLE
The gateway does not trim, summarise or re-encode provider replies on either path. Verified by
requesting a 250-line ordered sequence and checking every line survived: buffered and streamed
produced identical content, and what the gateway stored matched what it delivered. Assemble deltas
by simple concatenation — they are raw fragments, not sentences, and a token may split mid-word.

# LONG-GENERATION MODELS (served by copying the provider's method)
A few models cannot be served by an ordinary buffered request AT ANY TIMEOUT: they think for tens of
seconds before emitting, so the gateway holds a silent socket and cannot tell working from dead.
For those, the gateway asks the vendor for a STREAM even when you sent stream:false, consumes it
server-side, and returns the assembled answer in the normal envelope. Bytes flow, so the call is
bounded by SILENCE rather than elapsed time.
  · Your code does not change — same request, same response shape.
  · result.limits.buffered_strategy tells you which path ran: "direct" or "via_stream".
  · GET /v1/models publishes it per model, so a picker can show it up front.
Measured on grok-4.6: a 30s window fails; the model's own strategy returns 4,361 chars in 57s.
Per model only — a direct call stays simpler wherever the ordinary window already fits.

# SHORT VS LONG — DIFFERENT HANDLING
Short reply  -> buffered is fine: one request, one JSON response, simplest to write.
Long reply   -> stream it. Buffered, the whole cost lands inside one window and the user sees
                nothing until it ends; streamed, the first token usually arrives under a second and
                the window only ever measures SILENCE.
The dividing line is per model, and the gateway gives you the numbers: max_tokens_suggested for the
budget, stream_recommended for the verdict (it is also set per-CALL when your max_tokens exceeds
what that model was measured to finish in time).

# PROVIDER FAULTS — BRANCH ON error.retriable, NOT ON THE MESSAGE TEXT
Every 503 carries a code and a boolean, so you never have to string-match English prose:
  PROVIDER_TIMEOUT          retriable:false  the gateway abandoned a BUFFERED generation at its 30s wall.
                                             Do not retry unchanged — it times out identically. Retry
                                             smaller (halve max_tokens), or switch to "stream": true.
  PROVIDER_NOT_CONFIGURED   retriable:false  no active provider key for that vendor (the error carries
                                             `vendor`). Permanent until an operator acts. Pick another
                                             model, or use GET /v1/models?configured=1 in your picker.
  PROVIDER_ERROR            retriable:true   a genuine transient upstream fault: retry 1–2× with
                                             backoff + jitter.
Treating every 503 as retriable costs three 30s failures — 90+ seconds — before the user sees anything,
and none of those retries can succeed.

# STREAMING — THE ANSWER TO LONG REPLIES
Send "stream": true and the 30s generation wall stops applying. The response is text/event-stream:

    event: start
    data: {"request_id":"req_…","model":"…","limits":{…}}

    event: delta
    data: {"text":"Cache-Control"}

    event: done
    data: {"usage":{…},"limits":{…},"latency_ms":46013}

    data: [DONE]

Exactly one `done` OR one `error` always arrives before `data: [DONE]`, so you never have to guess how the
stream ended. An `error` event carries code, retriable and partial_chars — a stream that dies mid-answer
still delivered real text, and you can keep it. Parse deltas incrementally; do not wait for the whole body.

Why this removes the wall: a buffered call must guess a timeout, because until the response lands it
cannot tell a slow model from a dead one. A stream can tell — tokens are either arriving or they are not —
so it is bounded by SILENCE (30s with no data), not by total length.

Measured here on 2026-08-17, two distinct wins:
  - IT REMOVES THE WALL. grok-4.6 at just max_tokens 512 fails buffered with 503 PROVIDER_TIMEOUT,
    because it spends 18.2 s reasoning before its first token; streamed, the same call finishes in
    18.9 s. Thinking time blew the budget, not output length.
  - IT REMOVES THE WAIT. claude-sonnet-5 at max_tokens 2500 does complete buffered, in 24.8 s — but
    with ~5 s of headroom and nothing shown to the user for 25 s. Streamed, the first token lands at
    3.5 s.
Streaming costs the same and is logged the same.

# IF YOU CANNOT STREAM — SIZING max_tokens FOR A BUFFERED CALL
BUFFERED GENERATIONS ARE STILL ABANDONED AT 30 SECONDS. A model writes until it finishes or hits
max_tokens, so max_tokens sets the worst-case output LENGTH and therefore the worst-case TIME. Against a
fixed 30s wall it is a time budget wearing a token label, so the safe value is per MODEL, not per API:

        safe max_tokens  ≈  (that model's tokens/sec) × 25        [25s, leaving margin]

The old trap, now half-closed: the gateway used to CLAMP an oversized max_tokens and carry on, so probing
for the largest accepted value returned the WRONG ceiling. It now REJECTS with 400 and hands back
max_output_tokens and max_tokens_suggested. What it still cannot do is check whether an in-range budget
will FINISH inside 30s — which is what max_tokens_suggested is for, and why streaming is the better answer.

Measured on this gateway, 2026-08-16, ~5,600-token prompts, non-streaming. These move as providers and
hardware change — treat them as a starting point and record your own:

    model                        tok/s   fits in one 30s call   notes
    claude-haiku-4-5             ~120    ~3,600
    deepseek-v4-pro              ~100    ~3,000
    deepseek-v4-flash             ~95    ~2,800
    doubao-seed-2-0-mini-260215   ~90    ~2,500
    gpt-5.6-terra                 ~90    ~2,500                 borderline at 4,096
    qwen3.5-flash                 ~85    ~2,000                 times out at 4,096

REASONING MODELS ARE ABSENT FROM THIS TABLE ON PURPOSE. claude-opus-5, claude-sonnet-5,
claude-fable-5, qwen3.8-max and grok-4.6 report tokens_per_sec: null because a rate does not
describe them — their cost is a large fixed thinking period plus a fast tail. grok-4.6 spent
18.2 s before its first token and then emitted 35 tokens, which computes to 2 tok/s and a "safe"
budget of zero. STREAM these models instead of sizing a buffered budget: a buffered grok-4.6 call
at 512 tokens returns 503 PROVIDER_TIMEOUT.

If you need MORE output than one buffered call can hold, stream it. If you genuinely cannot, the fallback
is to CONTINUE, not enlarge:
1. Ask for a safe max_tokens. If usage.completion_tokens comes back AT the budget the answer was cut off,
   so send [original prompt, assistant: text-so-far, "continue from exactly where you stopped"] and
   concatenate. Each part is its own sub-30s call.
2. Continuations get SLOWER, because each one re-sends everything written so far. Expect part N to run
   nearer the wall than part 1, and keep the finished parts when one fails.
3. On a timeout, HALVE that model's max_tokens and REMEMBER IT. There is rarely room to fail at 30s and
   then succeed within the same request; the value of a failure is what it teaches the next request.
4. Raise a learned-down budget only when a model's slowest call used well under the window (<70%). Part
   count alone is not evidence of headroom.
5. DO NOT hold one HTTP connection open for the whole thing. Behind a proxy (nginx defaults to a 60s read
   timeout) a multi-call answer returns an opaque 504 — the gateway calls are legal, the transport is not.
   Run generation as a background job and let the client poll.

# RATE LIMITS (per plan; tunable server-side)
free 30/min, 1,000/mo · pro 120/min, 100,000/mo · admin 600/min, unlimited.

# WHAT TO BUILD
Using the browser fetch API (no extra dependencies), produce one module that:
1. Keeps the CONFIG block above at the very TOP so BASE_URL / API_KEY are easy to change.
2. chat(messages): POST `${BASE_URL}/v1/chat` with header Authorization: Bearer ${API_KEY} and JSON body
   { messages:[{ role, content }] }; return result, or surface error.code + request_id.
3. Handle 200 ok · 401 (key invalid/expired) · 429 (honour Retry-After, back off) ·
   503 (PROVIDER_TIMEOUT / PROVIDER_NOT_CONFIGURED / PROVIDER_ERROR — branch on error.retriable; only the
       last of the three is worth retrying).
4. A tiny demo calling chat([{ role: "user", content: "Hello" }]).
Don't ship the key in public client JS — for production proxy via a same-site backend.

# Video integration — Stages 1–4 (GA00.0.19.142, 2026-10-14)

This current contract supersedes earlier Mini-only / unavailable-stage descriptions. Discover permitted models and modes at runtime; provider activation alone does not enable a gateway capability.

| Model ID | Available client modes | Estimated USD / million output tokens |
| :--- | :--- | ---: |
| dreamina-seedance-2-0-mini-260615 | txt2vid, imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 3.50 |
| dreamina-seedance-2-5-260628 | imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 10.70 at 480p/720p; 11.70 at 1080p |

# Routes and authentication

All four endpoints use Authorization: Bearer <gateway key>. Provider keys remain on the server. The same issued gateway key can be reused across video modes only when the corresponding active BytePlus video.<mode> credential and any explicit provider mapping permit it. Separate app settings do not require newly issued keys.

| Method | Path | Result |
| :--- | :--- | :--- |
| GET | /v1/video/models | result.models[]: id, vendor, modes, resolution, supported_resolutions, enabled_resolutions, duration_seconds, price_usd_per_m_completion_tokens; empty when no permitted credential exists |
| POST | /v1/video/tasks | Persist one UUID client_token before sending; 202 accepted, duplicate UUID returns saved task at 200 |
| GET | /v1/video/tasks/{request_id} | Refresh an owned task; 200 contains state, not proof of completion |
| GET | /v1/video/tasks?client_token=UUID | Recover saved task without another provider submission; 404 if absent |

Responses use {request_id, result, usage:null, error:null}; the top-level request_id identifies the HTTP request, while result.request_id identifies the saved generation task. Save the latter for polling. Another user's task returns 404.

# Submission and ordered references

POST JSON: {client_token:UUID, model, mode, prompt, resolution:"480p"|"720p"|"1080p", duration:5, images:[]}. A prompt of 1–4000 characters is required. supported_resolutions and enabled_resolutions list Mini 480p/720p and Seedance 2.5 480p/720p/1080p. Submit only an enabled resolution for the selected model; 1080p is 2.5-only. Whole-second duration is Mini 4–15 or 2.5 4–30; audio is off. txt2vid uses 16:9, image modes use adaptive ratio. Administrators can review recorded model/resolution usage at /video-analyst.html; it is not a public client API.

| Mode | images[] count and order | Provider roles assigned by gateway |
| :--- | :--- | :--- |
| txt2vid | 0 (omit or []) | none |
| imgf_txt2vid | 1: first frame | first_frame |
| imgfl_txt2vid | 2: first frame, then last frame | first_frame, last_frame |
| imgrs_txt2vid | exactly 2: reference 1, then reference 2 | reference_image, reference_image |

Each image is an original JPEG/PNG/WebP base64 data URL, no remote URL; the encoded URL must be at most 8,000,000 characters (keep original bytes below 5.9 MB). The app JSON ceiling is 16 MiB, but live nginx limits this public video route to 5 MiB total JSON (verified 2026-10-13). Keep the entire base64-expanded request below 5 MiB; this is a combined-body limit, not a per-image allowance. Do not reorder, crop or re-encode reference files silently. Clients send images[], not the provider's content/role schema. A reference image guides content, not a fixed first/last frame. Real-person inputs may be rejected by provider policy. Correct submission is not proof of visual adherence: compare actual sampled first/last frames separately; preserve failures in reports.

# Asynchronous status, recovery and downloads

Persist the immutable draft and UUID before POST. Poll the saved task approximately every 5 seconds while active, slowing down after failures or backgrounding. A provider POST has a 45-second submission timeout and status fetch a 20-second timeout; neither is the video render duration. Allow HTTP overhead (e.g. 60s submit / 30s status), then recover by UUID after a connection failure. Never automatically replace the token or resubmit an uncertain/rejected task. A 404 recovery is not permission for an automatic paid retry: ask the operator to review first. Idempotency-Key is not the video's duplicate mechanism; client_token is.

Read result.state even on HTTP 200: succeeded is the only successful terminal state; failed, cancelled, expired, rejected and submit_unknown stop automatic polling and require visible error/review. A rejected or uncertain submission can be returned as a saved task at HTTP 200. Validate result.output_url before playback/download; success without a usable URL is not a playable-video pass. Treat output URLs as temporary and download promptly. Use the UI labels Refresh video status and Download video from server. Keep references and signed URLs out of public logs.

# Tokens, response time and billing

result includes request_id, provider_task_id, model, mode, state, provider_status, completion_tokens, estimated_cost_usd, output_url, error_code, error_message, created_at, updated_at. Missing values are null, never invented zero. Input tokens and pure queue/render time are not published. Record client-observed end-to-end time separately from submit HTTP time; polling time is not provider render time.

cost_basis remains "estimated" and provider_confirmed_cost_usd remains null on this client API, even when a separate finance observation exists. Estimate = completion_tokens × selected-model rate / 1,000,000 (rounded to six decimals). For example, 48,437 Seedance 2.5 output tokens estimate US$0.518276. Polling and UUID reuse do not create a second generation charge/monthly generation-quota entry; normal authentication and transport errors still apply. Provider gross cost, plan deduction, cash payable and remaining balance are separate facts. A plan-covered charge is not a zero-cost generation. Confirm actual charges in the provider console with evidence; do not automatically mark the ledger confirmed.

# Platform handling

Android: persist draft/token before OkHttp POST; resume polling from stored result.request_id after process restart. iOS: persist draft/token before URLSession POST; keep the gateway key in Keychain, preserve original picker bytes, resume status after relaunch, download via URLSession for Save/Share. Web: keep privileged keys server-side in a backend-for-frontend, not a public bundle/localStorage; a controlled test bench can accept a short-lived restricted key in memory. Both HTTP and HTTPS gateway URLs are supported; HTTPS web pages must use the HTTPS URL to avoid mixed content. cURL: load the key from an environment variable and JSON from a file; retain the UUID and returned result.request_id, never use automatic POST retries.

# Verified test boundaries

Existing simulator reports are evidence, not a new test run: Mini first/last fidelity failures remain failures despite valid wire roles; Seedance 2.5 sampled endpoint composition passed with qualifications, not pixel identity or every-object motion. Reference-mode real-person rejection and the successful illustrated-reference retest remain separate cases. Full 2.0/Fast provider tests do not imply those models are exposed to public clients. No TestFlight or device-validation claim is made by this guide update.


# DEV LOG (required — we use this to improve the spec)
This spec is still evolving and the author cannot see your environment or where the spec was
unclear, so your log is the only feedback channel. Keep a DEV_LOG.md and deliver it with the code.
Purpose: capture real integration experience so the spec can be corrected and clarified.
Record at minimum:
- Build platform: OS + version, runtime / bundler / framework + versions, language (JS / TS) version.
- Target / deployment platform: browser(s) + versions, or Node version if server-side.
- Tools used: AI assistant + model, libraries + versions, anything else.
- What failed and how you solved it — or could NOT solve, and why.
- Anything in the spec that was missing, ambiguous, wrong, or that you had to assume.
- MEASURED NUMBERS, not just prose: observed tokens/sec per model you used, the largest max_tokens each
  one completed reliably, and any request that timed out (with its prompt size). Those three facts build
  the table in "# LONG ANSWERS", they change as providers and hardware change, and nobody can supply them
  from the server side.
- Any other detail that would help the next developer or improve the spec.

Edit the CONFIG block at the top (base URL + your API key), then copy the whole prompt and hand it to an AI coding assistant — it contains everything it needs to build a shell / REST integration. The bottom of this page is a manual reference if you'd rather write it yourself.

# API_Gateway · spec version {{GATEWAY_VERSION}} · last updated {{SPEC_UPDATED}}
# TASK
Write a POSIX shell script (curl + jq) that talks to our AI Gateway, following the spec below.

# ===== CONFIG (edit these — kept at the TOP so they're easy to find & change) =====
BASE_URL="{{BASE_URL}}"
API_KEY="PASTE_YOUR_GATEWAY_API_KEY_HERE"   # sent as: Authorization: Bearer <API_KEY>
# =====================================================================================

# ABOUT THE SYSTEM (read this)
Transport: HTTPS https://api-gateway.wmazing.cloud (recommended); HTTP http://api-gateway.wmazing.cloud is also supported. No forced redirect or HSTS upgrade. Set BASE_URL to either complete URL, without a trailing /v1.

The gateway sits in front of an AI provider. Clients call the gateway, never the
provider directly — provider keys never leave the server. All endpoints live under
$BASE_URL/v1. Every response carries an X-Request-Id header for tracing. Success bodies (HTTP 2xx) are JSON
{ request_id, result, usage, error:null }; error bodies (HTTP 4xx/5xx) are { error:{ code, message,
request_id } } — there is NO top-level request_id/result/usage on errors, so read the id from
error.request_id or the X-Request-Id header.

# AUTH
Send your key on every call:  Authorization: Bearer <API_KEY>
(Get the key from the gateway console. A 401 means the key is missing, invalid, or expired.)

# ENDPOINTS
POST /v1/chat   { messages:[{role,content}], model?, max_tokens? }   (messages must be non-empty)
                LIVE — the gateway proxies to the AI provider. Success result:
                { type:"text", model, message:{role:"assistant",content}, latency_ms, provider_request_id },
                plus a usage:{prompt_tokens,completion_tokens,total_tokens} block — parse result.message.content.
                model? optional (defaults to the first enabled text model; or pass an id from GET /v1/models).
                max_tokens? is VALIDATED against the model's own max_output_tokens, not clamped (default
                  1024). Above the ceiling you get 400 naming it, plus max_tokens_suggested. Read the
                  ceiling from GET /v1/models; the reply echoes what was applied in
                  result.limits.max_tokens_applied. A conversation longer than the model's context window
                  is refused with 413 before any provider call is spent.
                "stream": true IS SUPPORTED — see "# STREAMING" below. Streaming is the right answer for
                  anything longer than a short reply: it is not subject to the buffered generation wall.
                timeout_ms? optional — YOUR window, in milliseconds. Clamped to the model's ceiling: you may
                  ask for less, never more. The window actually in force comes back as
                  result.limits.timeout_ms (and in the SSE `start` event, BEFORE the first token), with
                  timeout_source (measured|default) and timeout_clamped so you are never silently given a
                  different deal than you asked for.
# --- Image understanding / 看圖答問 (LIVE) — image in, TEXT out ---
POST /v1/img2txt   { image | images:[...], prompt, model?, image_mime?, max_tokens?, timeout_ms? }
                image = base64 or a data: URL of ONE photo; images = an array (max 8) to ask about several
                at once. prompt = the QUESTION about the picture ("How many people are in this image?").
                This is a TEXT call that happens to take a picture: it resolves from the TEXT model catalog,
                is billed per token, and returns a message — never an image. model? must be a VISION-capable
                text model THAT THIS GATEWAY HAS ENABLED for it; discover them with
                GET /v1/models?vision=1, which lists exactly those (each entry carries
                capabilities.vision = the model can read images, and capabilities.img2txt = this gateway
                accepts image questions on it; you need the second). Omit model? and the gateway picks the
                first enabled one. A model that is not enabled — or cannot see at all — is refused 400
                rather than silently answering from the prompt alone, which is what several providers
                themselves do and the reason the check lives here instead of at the vendor.
                Success result: { type:"text", ai_type:"text.img2txt", model, message:{role,content},
                image_count, latency_ms, provider_request_id, limits } — read message.content for the answer.
                No streaming on this route: the whole wait is the model LOOKING at the picture, which a
                stream cannot make visible. Bodies allow up to 64 MB, like the image routes.
# --- Image generation (LIVE — gateway holds the provider credential) ---
# TIMING: image windows are PER MODEL AND PER CAPABILITY, and they are wide. Measured:
#   qwen-image-2.0-pro  12s with no source photo, 20s with one, 279s with two.
#   gpt-image-2         ~25-30s typically, but 60s has been seen on the same request.
# So do NOT assume ~10s and do NOT set a short client-side HTTP timeout: budget minutes
# for multi_image2image. Every image reply carries result.limits — timeout_ms (the window
# actually applied), timeout_source, timeout_clamped, buffered_strategy — so you can show a
# realistic progress expectation instead of guessing. Send timeout_ms to ask for a SHORTER
# window than the model's; you can never ask for a longer one, and if you try, the reply
# says so via timeout_clamped:true. buffered_strategy is "direct" or "via_stream": on
# via_stream the gateway is consuming the provider's own image stream on your behalf and
# judging the call by silence, which is why those models no longer time out.
POST /v1/txt2image          { prompt, model?, size?, timeout_ms? }         no source image.
POST /v1/image2image        { image, prompt, model?, image_mime?, size?, timeout_ms? }
                                                                          image = base64 or data: URL of ONE source photo.
POST /v1/multi_image2image  { images:[...], prompt, model?, size?, timeout_ms? }
                                                                          images = non-empty array of base64/data-URL photos (max 16).
                model? defaults to qwen-image-2.0 (handles all three). One gateway key authenticates every
                route (auth is per-user). Success result: { type:"image", ai_type, model,
                images:[{url}|{b64,mime}], latency_ms, provider_request_id }. Qwen returns a SIGNED URL that
                expires in ~24h — fetch/cache promptly, don't persist it. A model must be
                enabled for the capability or you get 400 VALIDATION_ERROR "Model … is not enabled for <cap>".
                Image bodies allow up to 64 MB (vs 256 KB JSON); nginx caps the body too — keep images small.
                size? IS OPTIONAL AND THE RULES ARE THE VENDOR'S — the gateway forwards your value unchanged and
                validates nothing. Omitting it (vendor default) is safest. If you send it: "WIDTHxHEIGHT", lower-case
                x, e.g. "1024x1024". NOT "width*height", NOT "2k", NOT "1:3". Per vendor:
                  openai  gpt-image-…      both dimensions divisible by 16, and not below the model's min pixel budget.
                  ark     doubao-seedream- at least 3,686,400 px total (1536x2048 = 3,145,728 is REFUSED); 1k/2k/4k ok.
                  qwen    qwen-image-…     send "WIDTHxHEIGHT" too — the gateway rewrites it to DashScope's
                                           "width*height". It is the ONLY vendor it rewrites for, so a "*" copied
                                           from DashScope docs fails on every other model here.
                A bad size returns 400 VALIDATION_ERROR carrying the VENDOR'S OWN sentence in error.message
                (e.g. "image size must be at least 3686400 pixels"). Read it and change the value — retrying the
                same size returns the same 400 and still spends a request from the quota.
GET  /v1/usage  -> caller's month-to-date usage + plan limit
GET  /v1/image-models -> the IMAGE models this gateway offers. /v1/models is TEXT ONLY and never lists an
                image model, so this is the ONLY way to discover them; use a returned id as the "model" for
                /v1/txt2image, /v1/image2image and /v1/multi_image2image. Each entry carries capabilities
                {txt2image, img2image, multi_image} saying which of those three routes it is valid for, plus
                max_images (the multi_image2image reference cap) and servable.
                servable:false means DO NOT OFFER IT — either the gateway holds no key for that vendor, or the
                vendor permanently refused the model on the last real call (unservable_reason tells you which:
                no_provider_key | vendor_refused; last_status/last_at are the evidence). A vendor can refuse a
                model the gateway has correctly enabled — e.g. an Ark account that has not activated it — and
                no gateway setting fixes that. Use GET /v1/image-models?servable=1 so your picker never offers
                one that cannot run; result.unservable counts what was left out.
GET  /v1/models -> models this gateway offers; use a returned id as /v1/chat's "model" (one key works for all).
                Each entry carries timeout_ms (the window that model gets for ONE buffered generation — set
                per model from measurement, not a flat default), timeout_source and stream_recommended.
                READ THE WINDOW BEFORE THE CONVERSATION STARTS so both sides agree what "too long" means.
                Each entry carries max_input_tokens / max_output_tokens / limits_verified — read those
                instead of guessing — plus `configured` (false = the gateway holds no active key for that
                vendor, so the model is listed but answers 503 PROVIDER_NOT_CONFIGURED) and the measured
                tokens_per_sec / max_tokens_suggested (null = never measured, NOT unlimited).
                Use GET /v1/models?configured=1 to list only models that will actually run;
                result.unconfigured counts what was filtered out. Build your picker from that.
GET  /health    -> liveness (no auth)

# ERRORS (read HTTP status + error.code, print request_id)
400/413 VALIDATION_ERROR · 401 AUTH_REQUIRED / AUTH_INVALID (key missing/invalid/expired) ·
429 RATE_LIMITED / QUOTA_EXCEEDED (honour Retry-After) ·
503 PROVIDER_TIMEOUT / PROVIDER_NOT_CONFIGURED / PROVIDER_ERROR (see the fault table below).

# WHICH OF THE THREE PARTIES STOPPED?
Provider, gateway, client — any of them can end a call, and they need different responses:
  503 PROVIDER_TIMEOUT (JSON body, retriable:false, carries timeout_ms + stream_recommended)
      THE GATEWAY gave up at its window. The message names the fix. Never a silent hang.
  504 with no JSON body
      THE REVERSE PROXY, not the gateway — your requested window outran the proxy's own limit.
      Lower timeout_ms, or stream.
  stream ends with no `done` and no `error` event
      THE CLIENT or the network dropped it. Every gateway-side ending is explicit: exactly one
      `done` or one `error` always precedes `data: [DONE]`.

# CONTENT IS PASSED THROUGH WHOLE
The gateway does not trim, summarise or re-encode provider replies on either path. Verified by
requesting a 250-line ordered sequence and checking every line survived: buffered and streamed
produced identical content, and what the gateway stored matched what it delivered. Assemble deltas
by simple concatenation — they are raw fragments, not sentences, and a token may split mid-word.

# LONG-GENERATION MODELS (served by copying the provider's method)
A few models cannot be served by an ordinary buffered request AT ANY TIMEOUT: they think for tens of
seconds before emitting, so the gateway holds a silent socket and cannot tell working from dead.
For those, the gateway asks the vendor for a STREAM even when you sent stream:false, consumes it
server-side, and returns the assembled answer in the normal envelope. Bytes flow, so the call is
bounded by SILENCE rather than elapsed time.
  · Your code does not change — same request, same response shape.
  · result.limits.buffered_strategy tells you which path ran: "direct" or "via_stream".
  · GET /v1/models publishes it per model, so a picker can show it up front.
Measured on grok-4.6: a 30s window fails; the model's own strategy returns 4,361 chars in 57s.
Per model only — a direct call stays simpler wherever the ordinary window already fits.

# SHORT VS LONG — DIFFERENT HANDLING
Short reply  -> buffered is fine: one request, one JSON response, simplest to write.
Long reply   -> stream it. Buffered, the whole cost lands inside one window and the user sees
                nothing until it ends; streamed, the first token usually arrives under a second and
                the window only ever measures SILENCE.
The dividing line is per model, and the gateway gives you the numbers: max_tokens_suggested for the
budget, stream_recommended for the verdict (it is also set per-CALL when your max_tokens exceeds
what that model was measured to finish in time).

# PROVIDER FAULTS — BRANCH ON error.retriable, NOT ON THE MESSAGE TEXT
Every 503 carries a code and a boolean, so you never have to string-match English prose:
  PROVIDER_TIMEOUT          retriable:false  the gateway abandoned a BUFFERED generation at its 30s wall.
                                             Do not retry unchanged — it times out identically. Retry
                                             smaller (halve max_tokens), or switch to "stream": true.
  PROVIDER_NOT_CONFIGURED   retriable:false  no active provider key for that vendor (the error carries
                                             `vendor`). Permanent until an operator acts. Pick another
                                             model, or use GET /v1/models?configured=1 in your picker.
  PROVIDER_ERROR            retriable:true   a genuine transient upstream fault: retry 1–2× with
                                             backoff + jitter.
Treating every 503 as retriable costs three 30s failures — 90+ seconds — before the user sees anything,
and none of those retries can succeed.

# STREAMING — THE ANSWER TO LONG REPLIES
Send "stream": true and the 30s generation wall stops applying. The response is text/event-stream:

    event: start
    data: {"request_id":"req_…","model":"…","limits":{…}}

    event: delta
    data: {"text":"Cache-Control"}

    event: done
    data: {"usage":{…},"limits":{…},"latency_ms":46013}

    data: [DONE]

Exactly one `done` OR one `error` always arrives before `data: [DONE]`, so you never have to guess how the
stream ended. An `error` event carries code, retriable and partial_chars — a stream that dies mid-answer
still delivered real text, and you can keep it. Parse deltas incrementally; do not wait for the whole body.

Why this removes the wall: a buffered call must guess a timeout, because until the response lands it
cannot tell a slow model from a dead one. A stream can tell — tokens are either arriving or they are not —
so it is bounded by SILENCE (30s with no data), not by total length.

Measured here on 2026-08-17, two distinct wins:
  - IT REMOVES THE WALL. grok-4.6 at just max_tokens 512 fails buffered with 503 PROVIDER_TIMEOUT,
    because it spends 18.2 s reasoning before its first token; streamed, the same call finishes in
    18.9 s. Thinking time blew the budget, not output length.
  - IT REMOVES THE WAIT. claude-sonnet-5 at max_tokens 2500 does complete buffered, in 24.8 s — but
    with ~5 s of headroom and nothing shown to the user for 25 s. Streamed, the first token lands at
    3.5 s.
Streaming costs the same and is logged the same.

# IF YOU CANNOT STREAM — SIZING max_tokens FOR A BUFFERED CALL
BUFFERED GENERATIONS ARE STILL ABANDONED AT 30 SECONDS. A model writes until it finishes or hits
max_tokens, so max_tokens sets the worst-case output LENGTH and therefore the worst-case TIME. Against a
fixed 30s wall it is a time budget wearing a token label, so the safe value is per MODEL, not per API:

        safe max_tokens  ≈  (that model's tokens/sec) × 25        [25s, leaving margin]

The old trap, now half-closed: the gateway used to CLAMP an oversized max_tokens and carry on, so probing
for the largest accepted value returned the WRONG ceiling. It now REJECTS with 400 and hands back
max_output_tokens and max_tokens_suggested. What it still cannot do is check whether an in-range budget
will FINISH inside 30s — which is what max_tokens_suggested is for, and why streaming is the better answer.

Measured on this gateway, 2026-08-16, ~5,600-token prompts, non-streaming. These move as providers and
hardware change — treat them as a starting point and record your own:

    model                        tok/s   fits in one 30s call   notes
    claude-haiku-4-5             ~120    ~3,600
    deepseek-v4-pro              ~100    ~3,000
    deepseek-v4-flash             ~95    ~2,800
    doubao-seed-2-0-mini-260215   ~90    ~2,500
    gpt-5.6-terra                 ~90    ~2,500                 borderline at 4,096
    qwen3.5-flash                 ~85    ~2,000                 times out at 4,096

REASONING MODELS ARE ABSENT FROM THIS TABLE ON PURPOSE. claude-opus-5, claude-sonnet-5,
claude-fable-5, qwen3.8-max and grok-4.6 report tokens_per_sec: null because a rate does not
describe them — their cost is a large fixed thinking period plus a fast tail. grok-4.6 spent
18.2 s before its first token and then emitted 35 tokens, which computes to 2 tok/s and a "safe"
budget of zero. STREAM these models instead of sizing a buffered budget: a buffered grok-4.6 call
at 512 tokens returns 503 PROVIDER_TIMEOUT.

If you need MORE output than one buffered call can hold, stream it. If you genuinely cannot, the fallback
is to CONTINUE, not enlarge:
1. Ask for a safe max_tokens. If usage.completion_tokens comes back AT the budget the answer was cut off,
   so send [original prompt, assistant: text-so-far, "continue from exactly where you stopped"] and
   concatenate. Each part is its own sub-30s call.
2. Continuations get SLOWER, because each one re-sends everything written so far. Expect part N to run
   nearer the wall than part 1, and keep the finished parts when one fails.
3. On a timeout, HALVE that model's max_tokens and REMEMBER IT. There is rarely room to fail at 30s and
   then succeed within the same request; the value of a failure is what it teaches the next request.
4. Raise a learned-down budget only when a model's slowest call used well under the window (<70%). Part
   count alone is not evidence of headroom.
5. DO NOT hold one HTTP connection open for the whole thing. Behind a proxy (nginx defaults to a 60s read
   timeout) a multi-call answer returns an opaque 504 — the gateway calls are legal, the transport is not.
   Run generation as a background job and let the client poll.

# RATE LIMITS (per plan; tunable server-side)
free 30/min, 1,000/mo · pro 120/min, 100,000/mo · admin 600/min, unlimited.

# WHAT TO BUILD
A single shell script that:
1. Keeps the CONFIG block above at the very TOP so BASE_URL / API_KEY are easy to change.
2. Defines chat() that POSTs "$BASE_URL/v1/chat" with header "Authorization: Bearer $API_KEY"
   and body { messages:[{role,content}] }, printing the response + X-Request-Id.
3. Echoes a clear message on non-2xx (429 -> show Retry-After, 503 -> upstream provider failed/timed out).
Use only curl and jq; keep the key in the CONFIG var, not scattered through the script.

# Video integration — Stages 1–4 (GA00.0.19.142, 2026-10-14)

This current contract supersedes earlier Mini-only / unavailable-stage descriptions. Discover permitted models and modes at runtime; provider activation alone does not enable a gateway capability.

| Model ID | Available client modes | Estimated USD / million output tokens |
| :--- | :--- | ---: |
| dreamina-seedance-2-0-mini-260615 | txt2vid, imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 3.50 |
| dreamina-seedance-2-5-260628 | imgf_txt2vid, imgfl_txt2vid, imgrs_txt2vid | 10.70 at 480p/720p; 11.70 at 1080p |

# Routes and authentication

All four endpoints use Authorization: Bearer <gateway key>. Provider keys remain on the server. The same issued gateway key can be reused across video modes only when the corresponding active BytePlus video.<mode> credential and any explicit provider mapping permit it. Separate app settings do not require newly issued keys.

| Method | Path | Result |
| :--- | :--- | :--- |
| GET | /v1/video/models | result.models[]: id, vendor, modes, resolution, supported_resolutions, enabled_resolutions, duration_seconds, price_usd_per_m_completion_tokens; empty when no permitted credential exists |
| POST | /v1/video/tasks | Persist one UUID client_token before sending; 202 accepted, duplicate UUID returns saved task at 200 |
| GET | /v1/video/tasks/{request_id} | Refresh an owned task; 200 contains state, not proof of completion |
| GET | /v1/video/tasks?client_token=UUID | Recover saved task without another provider submission; 404 if absent |

Responses use {request_id, result, usage:null, error:null}; the top-level request_id identifies the HTTP request, while result.request_id identifies the saved generation task. Save the latter for polling. Another user's task returns 404.

# Submission and ordered references

POST JSON: {client_token:UUID, model, mode, prompt, resolution:"480p"|"720p"|"1080p", duration:5, images:[]}. A prompt of 1–4000 characters is required. supported_resolutions and enabled_resolutions list Mini 480p/720p and Seedance 2.5 480p/720p/1080p. Submit only an enabled resolution for the selected model; 1080p is 2.5-only. Whole-second duration is Mini 4–15 or 2.5 4–30; audio is off. txt2vid uses 16:9, image modes use adaptive ratio. Administrators can review recorded model/resolution usage at /video-analyst.html; it is not a public client API.

| Mode | images[] count and order | Provider roles assigned by gateway |
| :--- | :--- | :--- |
| txt2vid | 0 (omit or []) | none |
| imgf_txt2vid | 1: first frame | first_frame |
| imgfl_txt2vid | 2: first frame, then last frame | first_frame, last_frame |
| imgrs_txt2vid | exactly 2: reference 1, then reference 2 | reference_image, reference_image |

Each image is an original JPEG/PNG/WebP base64 data URL, no remote URL; the encoded URL must be at most 8,000,000 characters (keep original bytes below 5.9 MB). The app JSON ceiling is 16 MiB, but live nginx limits this public video route to 5 MiB total JSON (verified 2026-10-13). Keep the entire base64-expanded request below 5 MiB; this is a combined-body limit, not a per-image allowance. Do not reorder, crop or re-encode reference files silently. Clients send images[], not the provider's content/role schema. A reference image guides content, not a fixed first/last frame. Real-person inputs may be rejected by provider policy. Correct submission is not proof of visual adherence: compare actual sampled first/last frames separately; preserve failures in reports.

# Asynchronous status, recovery and downloads

Persist the immutable draft and UUID before POST. Poll the saved task approximately every 5 seconds while active, slowing down after failures or backgrounding. A provider POST has a 45-second submission timeout and status fetch a 20-second timeout; neither is the video render duration. Allow HTTP overhead (e.g. 60s submit / 30s status), then recover by UUID after a connection failure. Never automatically replace the token or resubmit an uncertain/rejected task. A 404 recovery is not permission for an automatic paid retry: ask the operator to review first. Idempotency-Key is not the video's duplicate mechanism; client_token is.

Read result.state even on HTTP 200: succeeded is the only successful terminal state; failed, cancelled, expired, rejected and submit_unknown stop automatic polling and require visible error/review. A rejected or uncertain submission can be returned as a saved task at HTTP 200. Validate result.output_url before playback/download; success without a usable URL is not a playable-video pass. Treat output URLs as temporary and download promptly. Use the UI labels Refresh video status and Download video from server. Keep references and signed URLs out of public logs.

# Tokens, response time and billing

result includes request_id, provider_task_id, model, mode, state, provider_status, completion_tokens, estimated_cost_usd, output_url, error_code, error_message, created_at, updated_at. Missing values are null, never invented zero. Input tokens and pure queue/render time are not published. Record client-observed end-to-end time separately from submit HTTP time; polling time is not provider render time.

cost_basis remains "estimated" and provider_confirmed_cost_usd remains null on this client API, even when a separate finance observation exists. Estimate = completion_tokens × selected-model rate / 1,000,000 (rounded to six decimals). For example, 48,437 Seedance 2.5 output tokens estimate US$0.518276. Polling and UUID reuse do not create a second generation charge/monthly generation-quota entry; normal authentication and transport errors still apply. Provider gross cost, plan deduction, cash payable and remaining balance are separate facts. A plan-covered charge is not a zero-cost generation. Confirm actual charges in the provider console with evidence; do not automatically mark the ledger confirmed.

# Platform handling

Android: persist draft/token before OkHttp POST; resume polling from stored result.request_id after process restart. iOS: persist draft/token before URLSession POST; keep the gateway key in Keychain, preserve original picker bytes, resume status after relaunch, download via URLSession for Save/Share. Web: keep privileged keys server-side in a backend-for-frontend, not a public bundle/localStorage; a controlled test bench can accept a short-lived restricted key in memory. Both HTTP and HTTPS gateway URLs are supported; HTTPS web pages must use the HTTPS URL to avoid mixed content. cURL: load the key from an environment variable and JSON from a file; retain the UUID and returned result.request_id, never use automatic POST retries.

# Verified test boundaries

Existing simulator reports are evidence, not a new test run: Mini first/last fidelity failures remain failures despite valid wire roles; Seedance 2.5 sampled endpoint composition passed with qualifications, not pixel identity or every-object motion. Reference-mode real-person rejection and the successful illustrated-reference retest remain separate cases. Full 2.0/Fast provider tests do not imply those models are exposed to public clients. No TestFlight or device-validation claim is made by this guide update.


# DEV LOG (required — we use this to improve the spec)
This spec is still evolving and the author cannot see your environment or where the spec was
unclear, so your log is the only feedback channel. Keep a DEV_LOG.md and deliver it with the script.
Purpose: capture real integration experience so the spec can be corrected and clarified.
Record at minimum:
- Build platform: OS + version, shell + version, curl / jq versions.
- Target / deployment platform: where the script runs (CI, server, laptop) + OS.
- Tools used: AI assistant + model, any other utilities.
- What failed and how you solved it — or could NOT solve, and why.
- Anything in the spec that was missing, ambiguous, wrong, or that you had to assume.
- MEASURED NUMBERS, not just prose: observed tokens/sec per model you used, the largest max_tokens each
  one completed reliably, and any request that timed out (with its prompt size). Those three facts build
  the table in "# LONG ANSWERS", they change as providers and hardware change, and nobody can supply them
  from the server side.
- Any other detail that would help the next developer or improve the spec.