<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: HotAPI</title>
    <description>The latest articles on DEV Community by HotAPI (@dikese411980).</description>
    <link>https://dev.to/dikese411980</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4248227%2F961a56a8-d103-492b-a9e9-62da66d36daf.png</url>
      <title>DEV Community: HotAPI</title>
      <link>https://dev.to/dikese411980</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/dikese411980"/>
    <language>en</language>
    <item>
      <title>Migrating OpenAI chat, image editing, and voice pipelines to a single pay-as-you-go multimodal gateway</title>
      <dc:creator>HotAPI</dc:creator>
      <pubDate>Mon, 16 Nov 2026 17:38:26 +0000</pubDate>
      <link>https://dev.to/dikese411980/migrating-openai-chat-image-editing-and-voice-pipelines-to-a-single-pay-as-you-go-multimodal-4dim</link>
      <guid>https://dev.to/dikese411980/migrating-openai-chat-image-editing-and-voice-pipelines-to-a-single-pay-as-you-go-multimodal-4dim</guid>
      <description>&lt;p&gt;Teams building AI companions, creative editors, or interactive voice apps rarely stay on one model provider for long. Within weeks, a codebase ends up splitting chat completions across an OpenAI-compatible host, routing image edits to a separate diffusion endpoint with custom auth headers, polling a third service for text-to-speech, and maintaining three prepaid wallets with stranded balances.&lt;/p&gt;

&lt;p&gt;Every extra provider multiplies failure points: mismatched error envelopes, inconsistent safety classifier refusals mid-session, and divergent retry logic across SDKs. Consolidating synchronous chat (&lt;code&gt;silly-2.0&lt;/code&gt;), instruction-based image editing and character-locked stills (&lt;code&gt;seedream-5.0-pro-spicy&lt;/code&gt;, &lt;code&gt;qwen-image-2.1-spicy&lt;/code&gt;, &lt;code&gt;qwen-image-edit-spicy&lt;/code&gt;, &lt;code&gt;z-image-spicy&lt;/code&gt;), and expressive speech (&lt;code&gt;siren-1.0-spicy&lt;/code&gt;) onto a single OpenAI-compatible and async task gateway removes vendor sprawl and settles every workload against one credit balance.&lt;/p&gt;

&lt;p&gt;This migration walkthrough covers exact request shapes, OpenAI SDK diffs, CLI dry-run verification, and unit-cost budgeting on &lt;a href="https://hotapi.ai/en" rel="noopener noreferrer"&gt;HotAPI&lt;/a&gt;, anchored to the &lt;a href="https://hotapi.ai/en/docs/getting-started" rel="noopener noreferrer"&gt;API getting started guide&lt;/a&gt; and &lt;a href="https://hotapi.ai/en/pricing" rel="noopener noreferrer"&gt;live pricing schedule&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What actually changes when you point the OpenAI SDK at HotAPI for Silly 2.0 chat?
&lt;/h2&gt;

&lt;p&gt;Synchronous and SSE streaming chat completions require changing only &lt;code&gt;baseURL&lt;/code&gt;, &lt;code&gt;apiKey&lt;/code&gt;, and &lt;code&gt;model&lt;/code&gt; to &lt;code&gt;silly-2.0&lt;/code&gt;, because &lt;code&gt;POST /v1/chat/completions&lt;/code&gt; emits standard OpenAI response objects, &lt;code&gt;chat.completion.chunk&lt;/code&gt; stream frames, and &lt;code&gt;tool_calls&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Built on GLM-5.3 open weights post-trained for roleplay, &lt;a href="https://hotapi.ai/en/models/silly-2.0" rel="noopener noreferrer"&gt;Silly 2.0&lt;/a&gt; (&lt;a href="https://hotapi.ai/en/models/silly-2.0/chat" rel="noopener noreferrer"&gt;chat completions endpoint spec&lt;/a&gt;) exposes a 74K+ token context window and keeps internal reasoning on a separate &lt;code&gt;reasoning&lt;/code&gt; channel so planning notes never spill into visible character prose. Unlike image and video routes, chat is synchronous or SSE-streamed and does not accept &lt;code&gt;Idempotency-Key&lt;/code&gt; or &lt;code&gt;?webhook=&lt;/code&gt;. Billing settles token by token at &lt;code&gt;9,000&lt;/code&gt; credits (&lt;code&gt;$9.00&lt;/code&gt;) per 1M input tokens and &lt;code&gt;30,000&lt;/code&gt; credits (&lt;code&gt;$30.00&lt;/code&gt;) per 1M output tokens (&lt;code&gt;1,000 credits = $1.00 USD&lt;/code&gt;): the gateway holds an upper-bound reservation from &lt;code&gt;max_tokens&lt;/code&gt; (default &lt;code&gt;4096&lt;/code&gt;) and refunds unused credits once token counts return.&lt;/p&gt;

&lt;p&gt;For TypeScript apps using the Vercel AI SDK, pair &lt;code&gt;@ai-sdk/openai-compatible&lt;/code&gt; with &lt;code&gt;https://api.hotapi.ai/v1&lt;/code&gt; rather than &lt;code&gt;@ai-sdk/openai&lt;/code&gt;, because recent versions of &lt;code&gt;@ai-sdk/openai&lt;/code&gt; target &lt;code&gt;/v1/responses&lt;/code&gt; instead of &lt;code&gt;/v1/chat/completions&lt;/code&gt;. You can generate SDK diffs with the &lt;a href="https://hotapi.ai/en/tools/openai-to-hotapi-migrator" rel="noopener noreferrer"&gt;OpenAI to HotAPI migrator&lt;/a&gt; or read the &lt;a href="https://hotapi.ai/en/docs/guides/chat-completions" rel="noopener noreferrer"&gt;chat completions guide&lt;/a&gt;. Language-specific adapters live in the &lt;a href="https://hotapi.ai/en/integrations" rel="noopener noreferrer"&gt;integrations hub&lt;/a&gt;, including the &lt;a href="https://hotapi.ai/en/integrations/openai-sdk" rel="noopener noreferrer"&gt;OpenAI SDK integration blueprint&lt;/a&gt; and &lt;a href="https://hotapi.ai/en/integrations/vercel-ai-sdk" rel="noopener noreferrer"&gt;Vercel AI SDK integration guide&lt;/a&gt;, and architectural tradeoffs are laid out in &lt;a href="https://hotapi.ai/en/compare/hotapi-vs-replicate-fal" rel="noopener noreferrer"&gt;HotAPI vs Replicate and Fal.ai&lt;/a&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;OpenAI&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"openai"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;OpenAI&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;HOTAPI_KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;baseURL&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"https://api.hotapi.ai/v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;streamCompanionReply&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;userMessage&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;stream&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;chat&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;completions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"silly-2.0"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;max_tokens&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;600&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;temperature&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;0.85&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;stream&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;role&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"system"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="s2"&gt;"You are Maya, a night-shift diner owner who remembers regulars. Keep replies grounded in physical scene details."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;role&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"user"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;userMessage&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;reply&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;chunk&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="n"&gt;stream&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;token&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;chunk&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;choices&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;delta&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;reply&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;stdout&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;write&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;reply&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How do Seedream 5.0 Pro, Qwen Image 2.1, and Z-Image split editing vs generation workloads?
&lt;/h2&gt;

&lt;p&gt;Route multi-image blending and Pro instruction edits to &lt;code&gt;seedream-5.0-pro-spicy&lt;/code&gt;, single-source edits with up to two guide references to &lt;code&gt;qwen-image-edit-spicy&lt;/code&gt;, multi-scene character lock to &lt;code&gt;qwen-image-2.1-spicy&lt;/code&gt;, and high-volume seeded stills to &lt;code&gt;z-image-spicy&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;While chat stays synchronous on &lt;code&gt;/v1/chat/completions&lt;/code&gt;, every image, image-edit, and speech model uses one async contract: &lt;code&gt;POST&lt;/code&gt; returns &lt;code&gt;202 Accepted&lt;/code&gt; with a task &lt;code&gt;id&lt;/code&gt;, and your worker retrieves assets via &lt;code&gt;GET /v1/tasks/{id}&lt;/code&gt; or &lt;code&gt;?webhook=&lt;/code&gt;. That shared envelope means switching between an editorial blend, a wardrobe swap, and a character selfie never changes your queue or storage pipeline.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model slug&lt;/th&gt;
&lt;th&gt;API endpoint&lt;/th&gt;
&lt;th&gt;Input &amp;amp; reference caps&lt;/th&gt;
&lt;th&gt;Output spec&lt;/th&gt;
&lt;th&gt;Rate (1,000 cr = $1)&lt;/th&gt;
&lt;th&gt;Primary engineering use case&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;silly-2.0&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /v1/chat/completions&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;System/user/tool messages (&lt;code&gt;74K+&lt;/code&gt; ctx)&lt;/td&gt;
&lt;td&gt;Sync JSON or SSE chunks&lt;/td&gt;
&lt;td&gt;9,000 in / 30,000 out per 1M tok&lt;/td&gt;
&lt;td&gt;Persona-locked roleplay dialogue&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;seedream-5.0-pro-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /v1/seedream-5.0-pro-spicy/image-edit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1 HTTPS URL or array of 1-10 URLs + &lt;code&gt;prompt&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;size: "2K"&lt;/code&gt;, 8 aspect ratios&lt;/td&gt;
&lt;td&gt;120 cr / image (&lt;code&gt;$0.12&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Multi-image blending and Pro edits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;qwen-image-2.1-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /v1/qwen-image-2.1-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;prompt&lt;/code&gt; (&lt;code&gt;&amp;lt;= 4000&lt;/code&gt; chars) + up to 8 &lt;code&gt;reference_image_urls&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;1K&lt;/code&gt; or &lt;code&gt;2K&lt;/code&gt;, &lt;code&gt;n: 1-6&lt;/code&gt; images&lt;/td&gt;
&lt;td&gt;20 cr 1K (&lt;code&gt;$0.02&lt;/code&gt;) / 40 cr 2K (&lt;code&gt;$0.04&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Same synthetic character across scenes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;qwen-image-edit-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /v1/qwen-image-edit-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1 &lt;code&gt;image&lt;/code&gt; + up to 2 &lt;code&gt;reference_images&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Matches primary &lt;code&gt;image&lt;/code&gt; size, PNG&lt;/td&gt;
&lt;td&gt;80 cr / image (&lt;code&gt;$0.08&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Prompt-driven edits on existing stills&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;z-image-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /v1/z-image-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;prompt&lt;/code&gt; + optional &lt;code&gt;seed&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;256-1536px&lt;/code&gt; (&lt;code&gt;1024x1536&lt;/code&gt; default), PNG&lt;/td&gt;
&lt;td&gt;26 cr / image (&lt;code&gt;$0.026&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Fast seeded batch image generation&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;z-image-spicy-pro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /v1/z-image-spicy-pro&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;prompt&lt;/code&gt; + optional &lt;code&gt;seed&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;256-2560px&lt;/code&gt; (&lt;code&gt;1024x1024&lt;/code&gt; default), PNG&lt;/td&gt;
&lt;td&gt;30 cr / image (&lt;code&gt;$0.03&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;High-DPI stills up to &lt;code&gt;2560px&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;siren-1.0-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;POST /v1/siren-1.0-spicy&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;text&lt;/code&gt; (1-600 chars) + optional &lt;code&gt;voice&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;24 kHz mono WAV (~2 min max)&lt;/td&gt;
&lt;td&gt;40 cr / audio min (&lt;code&gt;$0.04&lt;/code&gt;, 3s min)&lt;/td&gt;
&lt;td&gt;Expressive character voice synthesis&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Watch three schema details when migrating workers. First, &lt;code&gt;/v1/seedream-5.0-pro-spicy/image-edit&lt;/code&gt; accepts either one HTTPS &lt;code&gt;image&lt;/code&gt; string or an array of 1 to 10 HTTPS URLs for blending, and its live OpenAPI contract restricts &lt;code&gt;size&lt;/code&gt; to &lt;code&gt;"2K"&lt;/code&gt; (&lt;code&gt;aspect_ratio&lt;/code&gt; optional). Second, passing &lt;code&gt;reference_image_urls&lt;/code&gt; to &lt;code&gt;qwen-image-2.1-spicy&lt;/code&gt; sets 2K 1:1 output to approximately &lt;code&gt;1536x1536&lt;/code&gt; rather than &lt;code&gt;2048x2048&lt;/code&gt;, and every reference image must stay within an &lt;code&gt;8:1&lt;/code&gt; aspect ratio. Third, &lt;code&gt;qwen-image-edit-spicy&lt;/code&gt; preserves the composition and dimensions of the primary &lt;code&gt;image&lt;/code&gt; URL while reading &lt;code&gt;reference_images&lt;/code&gt; in array order. Compare quality tradeoffs in the &lt;a href="https://hotapi.ai/en/compare/seedream-5-0-vs-qwen-image-2-1" rel="noopener noreferrer"&gt;Seedream 5.0 Pro vs Qwen Image 2.1 benchmark&lt;/a&gt;, or inspect individual model contracts for &lt;a href="https://hotapi.ai/en/models/seedream-5.0-pro-spicy/image-edit" rel="noopener noreferrer"&gt;Seedream 5.0 Pro image-edit&lt;/a&gt;, &lt;a href="https://hotapi.ai/en/models/qwen-image-2.1-spicy" rel="noopener noreferrer"&gt;Qwen Image 2.1&lt;/a&gt;, &lt;a href="https://hotapi.ai/en/models/qwen-image-edit-spicy" rel="noopener noreferrer"&gt;Qwen Image Edit&lt;/a&gt;, &lt;a href="https://hotapi.ai/en/models/z-image-spicy" rel="noopener noreferrer"&gt;Z-Image&lt;/a&gt;, &lt;a href="https://hotapi.ai/en/models/z-image-spicy-pro" rel="noopener noreferrer"&gt;Z-Image Pro&lt;/a&gt;, and the &lt;a href="https://hotapi.ai/en/docs/models" rel="noopener noreferrer"&gt;full model reference index&lt;/a&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;time&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;httpx&lt;/span&gt;

&lt;span class="no"&gt;HOTAPI_KEY&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;environ&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"HOTAPI_KEY"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="no"&gt;TERMINAL&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"succeeded"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"failed"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"cancelled"&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;blend_with_seedream_pro&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;image_urls&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;list&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;instruction&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;idempotency_key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="kt"&gt;list&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="n"&gt;httpx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Client&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;base_url&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"https://api.hotapi.ai"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"Authorization"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"Bearer {HOTAPI_KEY}"&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;timeout&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mf"&gt;30.0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;submit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
            &lt;span class="s2"&gt;"/v1/seedream-5.0-pro-spicy/image-edit"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"Idempotency-Key"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;idempotency_key&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="s2"&gt;"image"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;image_urls&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="s2"&gt;"prompt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;instruction&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="s2"&gt;"size"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2K"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="s2"&gt;"aspect_ratio"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"3:4"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="n"&gt;submit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raise_for_status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="n"&gt;task_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;submit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;

        &lt;span class="n"&gt;deadline&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;time&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;monotonic&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mf"&gt;180.0&lt;/span&gt;
        &lt;span class="k"&gt;while&lt;/span&gt; &lt;span class="n"&gt;time&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;monotonic&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;deadline&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
            &lt;span class="n"&gt;poll&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"/v1/tasks/{task_id}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="n"&gt;poll&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;raise_for_status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="n"&gt;task&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;poll&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;task&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="no"&gt;TERMINAL&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
                &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;task&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="s2"&gt;"succeeded"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
                    &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;RuntimeError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"Edit failed ({task_id}): {task.get('error')}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;asset&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;asset&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;task&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"output"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"assets"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
            &lt;span class="n"&gt;time&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sleep&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mf"&gt;2.0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;TimeoutError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"Timed out waiting for image edit task {task_id}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Why does Siren 1.0 charge per audio second instead of per input character?
&lt;/h2&gt;

&lt;p&gt;Billing &lt;code&gt;POST /v1/siren-1.0-spicy&lt;/code&gt; by generated WAV duration (&lt;code&gt;40&lt;/code&gt; credits, or &lt;code&gt;$0.04&lt;/code&gt;, per audio minute with a 3-second minimum) ensures slower-speaking languages and deliberate pauses never overcharge callers relative to output length.&lt;/p&gt;

&lt;p&gt;Because 100 characters take roughly 12 seconds to speak in English versus 20 seconds in Chinese, per-character TTS billing penalizes compact scripts. On Siren 1.0 Spicy, breaths, hesitations, and tone shifts come from natural punctuation and performance phrasing inside the 1-to-600-character &lt;code&gt;text&lt;/code&gt; field plus an optional &lt;code&gt;voice&lt;/code&gt; preset such as &lt;code&gt;"Kore"&lt;/code&gt;, without inline SSML tags. The gateway charges an initial reservation at submission and refunds the difference down to the exact length of the 24 kHz mono WAV asset once generation completes.&lt;/p&gt;

&lt;p&gt;Per-line speech synthesis fits directly beside streaming chat: split dialogue by turn or scene beat so a single retried inflection re-bills only a few seconds instead of a whole paragraph, as structured in the &lt;a href="https://hotapi.ai/en/models/siren-1.0-spicy/generate-speech" rel="noopener noreferrer"&gt;Siren 1.0 Spicy speech spec&lt;/a&gt; and the &lt;a href="https://hotapi.ai/en/playbooks/multimodal-ai-companion-architecture" rel="noopener noreferrer"&gt;multimodal AI companion architecture playbook&lt;/a&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -sS -X POST https://api.hotapi.ai/v1/siren-1.0-spicy \
  -H &lt;span class="s2"&gt;"Authorization: Bearer $HOTAPI_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Idempotency-Key: line_maya_014"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{
    "text": "Wait by the side door for ten seconds... the streetlamp out front is flickering again.",
    "voice": "Kore"
  }'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How do you validate schemas and run dry checks with hotapi-cli before writing backend code?
&lt;/h2&gt;

&lt;p&gt;Installing &lt;code&gt;hotapi-cli&lt;/code&gt; (Node.js 22+) lets you inspect live model schemas with &lt;code&gt;hotapi model schema &amp;lt;slug&amp;gt; --refresh&lt;/code&gt; and verify local payload parsing with &lt;code&gt;--dry-run --json&lt;/code&gt; before spending a credit or editing application code.&lt;/p&gt;

&lt;p&gt;Notice one environment variable boundary before running commands: HTTP integrations commonly read &lt;code&gt;HOTAPI_KEY&lt;/code&gt;, whereas the CLI reads &lt;code&gt;HOTAPI_API_KEY&lt;/code&gt; (or stores a key via &lt;code&gt;hotapi auth login --key-stdin&lt;/code&gt; in &lt;code&gt;~/.hotapi/config.json&lt;/code&gt; with mode &lt;code&gt;600&lt;/code&gt;). Non-TTY stdout always emits one machine-readable JSON object with predictable exit codes (&lt;code&gt;0&lt;/code&gt; success, &lt;code&gt;1&lt;/code&gt; bad input, &lt;code&gt;2&lt;/code&gt; invalid auth, &lt;code&gt;3&lt;/code&gt; API or task failure, &lt;code&gt;4&lt;/code&gt; missing task or schema, &lt;code&gt;5&lt;/code&gt; timeout, &lt;code&gt;6&lt;/code&gt; network failure, &lt;code&gt;130&lt;/code&gt; local interrupt without cancelling the remote task). Paid &lt;code&gt;POST&lt;/code&gt; requests never auto-retry inside the CLI; instead, each async submission records &lt;code&gt;_cli.idempotency_key&lt;/code&gt; so recovery scripts can inspect or replay safely. See the &lt;a href="https://hotapi.ai/en/cli" rel="noopener noreferrer"&gt;HotAPI CLI overview&lt;/a&gt; and &lt;a href="https://hotapi.ai/en/docs/guides/cli" rel="noopener noreferrer"&gt;CLI documentation&lt;/a&gt; for the full flag reference.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# CLI expects HOTAPI_API_KEY (separate from HTTP examples using HOTAPI_KEY)&lt;/span&gt;
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;HOTAPI_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"hk_live_..."&lt;/span&gt;
hotapi auth status --verify

&lt;span class="c"&gt;# Pull the live input schema before coding request structs&lt;/span&gt;
hotapi model list --modal image --output json &lt;span class="o"&gt;|&lt;/span&gt; jq &lt;span class="s1"&gt;'.data[] | .id'&lt;/span&gt;
hotapi model schema qwen-image-edit-spicy --refresh

&lt;span class="c"&gt;# Verify local parsing with zero network calls and zero credit charges&lt;/span&gt;
hotapi run qwen-image-edit-spicy \
  &lt;span class="nv"&gt;image&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;@./avatar.png \
  &lt;span class="nv"&gt;prompt&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"change jacket to matte black leather under cool rainlight"&lt;/span&gt; \
  --dry-run --json

&lt;span class="c"&gt;# Submit async, then wait and download output files to a clean directory&lt;/span&gt;
&lt;span class="nv"&gt;TASK_ID&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;hotapi run z-image-spicy \
  &lt;span class="nv"&gt;prompt&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"cinematic neon alleyway, wet pavement reflections"&lt;/span&gt; \
  &lt;span class="nv"&gt;width&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1024 &lt;span class="nv"&gt;height&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1024 --async --json &lt;span class="o"&gt;|&lt;/span&gt; jq -r &lt;span class="s1"&gt;'.id'&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;

hotapi task &lt;span class="nb"&gt;wait&lt;/span&gt; &lt;span class="s2"&gt;"$TASK_ID"&lt;/span&gt; --download --out-dir ./outputs --json
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How do you forecast monthly spend across chat, images, and voice on one credit wallet?
&lt;/h2&gt;

&lt;p&gt;Forecast monthly spend across one wallet by summing per-token chat charges, flat per-image fees, and exact-second voice durations against the fixed &lt;code&gt;1,000 credits = $1.00 USD&lt;/code&gt; exchange rate. Purchased credits never expire, so every modality draws down the same balance without separate vendor minimums.&lt;/p&gt;

&lt;p&gt;Consider a companion app running 2,000 active sessions per day totaling 1.5M Silly 2.0 input tokens (&lt;code&gt;13,500&lt;/code&gt; credits), 400K output tokens (&lt;code&gt;12,000&lt;/code&gt; credits), 500 Qwen Image 2.1 &lt;code&gt;1K&lt;/code&gt; selfies (&lt;code&gt;10,000&lt;/code&gt; credits), 100 &lt;code&gt;qwen-image-edit-spicy&lt;/code&gt; wardrobe edits (&lt;code&gt;8,000&lt;/code&gt; credits), and 60 minutes of Siren 1.0 voice replies (&lt;code&gt;2,400&lt;/code&gt; credits). Total daily spend equals &lt;code&gt;45,900&lt;/code&gt; credits, or &lt;code&gt;$45.90&lt;/code&gt; across all four capabilities with zero idle GPU retainers. You can model your own monthly traffic mix directly in the &lt;a href="https://hotapi.ai/en/tools/ai-api-pricing-calculator" rel="noopener noreferrer"&gt;AI API pricing calculator&lt;/a&gt; alongside the rest of the &lt;a href="https://hotapi.ai/en/tools" rel="noopener noreferrer"&gt;developer tools hub&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;When an organization balance runs low, requests fail fast before inference with &lt;code&gt;402 insufficient_credits&lt;/code&gt;. Because card payments and auto-top-up are not supported on self-serve BoomFi crypto top-ups (&lt;code&gt;$20&lt;/code&gt; to &lt;code&gt;$10,000&lt;/code&gt;), production workers should catch &lt;code&gt;402&lt;/code&gt; to alert operators and reconcile daily spend via &lt;code&gt;GET /v1/usage?from=YYYY-MM-DD&amp;amp;to=YYYY-MM-DD&lt;/code&gt; as described in the &lt;a href="https://hotapi.ai/en/docs/guides/billing" rel="noopener noreferrer"&gt;credits and billing guide&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>api</category>
      <category>openai</category>
      <category>typescript</category>
    </item>
    <item>
      <title>Handling 1080p reference-to-video timeouts, idempotent tasks, and HMAC webhooks</title>
      <dc:creator>HotAPI</dc:creator>
      <pubDate>Mon, 16 Nov 2026 17:32:39 +0000</pubDate>
      <link>https://dev.to/dikese411980/handling-1080p-reference-to-video-timeouts-idempotent-tasks-and-hmac-webhooks-jbg</link>
      <guid>https://dev.to/dikese411980/handling-1080p-reference-to-video-timeouts-idempotent-tasks-and-hmac-webhooks-jbg</guid>
      <description>&lt;p&gt;A 10-second 1080p reference-to-video render almost never finishes inside a standard 30-second HTTP timeout. When an application backend holds a reverse-proxy socket open while upstream GPU workers decode reference clips and synthesize hundreds of frames, Nginx or Cloudflare drops the connection and hands the caller a 504 gateway timeout.&lt;/p&gt;

&lt;p&gt;Blindly retrying that failed request creates a worse failure: the original job may already sit in the render queue, so a second POST spawns a duplicate video and charges the credit wallet twice. Splitting job submission from result delivery fixes both failure modes when you pair local media pre-uploads, a deterministic &lt;code&gt;Idempotency-Key&lt;/code&gt;, 480p draft or beat-planned prompt validation, and signed HMAC webhooks backed by cursor polling.&lt;/p&gt;

&lt;p&gt;The engineering patterns below map directly to the async task contract on &lt;a href="https://hotapi.ai/en" rel="noopener noreferrer"&gt;HotAPI&lt;/a&gt; and its &lt;a href="https://hotapi.ai/en/docs/getting-started" rel="noopener noreferrer"&gt;API getting started guide&lt;/a&gt;. Every snippet and table uses the live schemas for Seedance 2.5 Spicy (&lt;code&gt;seedance-2.5-spicy&lt;/code&gt;), Berry 1.0 Pro Spicy (&lt;code&gt;berry-1.0-pro-spicy&lt;/code&gt;), and Wan 3.0 (&lt;code&gt;w3.0-spicy&lt;/code&gt; and &lt;code&gt;w3.0-pro-spicy&lt;/code&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  What happens when a client retries a timed-out video POST without an idempotency key?
&lt;/h2&gt;

&lt;p&gt;Retrying a video &lt;code&gt;POST&lt;/code&gt; without an &lt;code&gt;Idempotency-Key&lt;/code&gt; header creates a second independent task and deducts credits again whenever the first request already crossed the API gateway boundary.&lt;/p&gt;

&lt;p&gt;Every generation call on &lt;code&gt;POST /v1/&amp;lt;model&amp;gt;&lt;/code&gt; or the unified &lt;code&gt;POST /v1/tasks&lt;/code&gt; route returns &lt;code&gt;202 Accepted&lt;/code&gt; immediately with &lt;code&gt;status: "queued"&lt;/code&gt;, &lt;code&gt;estimated_credits_cost&lt;/code&gt;, and the task &lt;code&gt;id&lt;/code&gt;. Passing an &lt;code&gt;Idempotency-Key&lt;/code&gt; header tied to your internal job ID turns network retries into safe replays: sending the same key with an identical JSON body returns &lt;code&gt;200 OK&lt;/code&gt; with the existing task object instead of queuing a duplicate render, while sending the same key with a modified payload returns &lt;code&gt;409 conflict_error&lt;/code&gt; (&lt;code&gt;idempotency_key_reused&lt;/code&gt;) so silent parameter drift fails loudly.&lt;/p&gt;

&lt;p&gt;If a user cancels a queued render before rendering begins, &lt;code&gt;DELETE /v1/tasks/{id}&lt;/code&gt; refunds &lt;code&gt;estimated_credits_cost&lt;/code&gt; in full only when &lt;code&gt;started_at&lt;/code&gt; is still &lt;code&gt;null&lt;/code&gt;. Once a worker picks up the job, the charge stands. Failed tasks refund automatically, and your submission client should still respect &lt;code&gt;429&lt;/code&gt; (&lt;code&gt;rate_limit_error&lt;/code&gt;) and &lt;code&gt;503&lt;/code&gt; (&lt;code&gt;service_unavailable&lt;/code&gt;) &lt;code&gt;Retry-After&lt;/code&gt; headers before sleeping, as detailed in the &lt;a href="https://hotapi.ai/en/docs/guides/async-tasks" rel="noopener noreferrer"&gt;HotAPI async tasks guide&lt;/a&gt; and the &lt;a href="https://hotapi.ai/en/models" rel="noopener noreferrer"&gt;model catalog&lt;/a&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;crypto&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"node:crypto"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;VideoJobRequest&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;jobId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;referenceImageUrls&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;durationSeconds&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;webhookUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;submitSeedanceReferenceJob&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;job&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;VideoJobRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;endpoint&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="s2"&gt;"https://api.hotapi.ai/v1/seedance-2.5-spicy/reference-to-video"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;endpoint&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"webhook"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;job&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;webhookUrl&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;payload&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;reference_image_urls&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;job&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;referenceImageUrls&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;job&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;duration_seconds&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;job&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;durationSeconds&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;resolution&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"480p"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;draft&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;generate_audio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// Derive a stable key from the internal job id so network retries replay cleanly.&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;idempotencyKey&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sb"&gt;`vid_${crypto
    .createHash("sha256")
    .update(job.jobId)
    .digest("hex")
    .slice(0, 24)}`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;endpoint&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;method&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"POST"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sb"&gt;`Bearer ${process.env.HOTAPI_KEY}`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"Idempotency-Key"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;idempotencyKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"Content-Type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"application/json"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;payload&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;AbortSignal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;15_000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;202&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;estimated_credits_cost&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;429&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;503&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;retryAfterSec&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"retry-after"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="s2"&gt;"5"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;setTimeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;retryAfterSec&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;continue&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;err&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="sb"&gt;`HotAPI submission failed (${res.status}) [${err?.error?.request_id}]: ${err?.error?.message}`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Exhausted retry budget submitting reference-to-video task"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How do Seedance 2.5, Berry 1.0 Pro, and Wan 3.0 differ on reference limits and billing?
&lt;/h2&gt;

&lt;p&gt;Seedance 2.5, Berry 1.0 Pro, and Wan 3.0 accept different ceilings for image, audio, video, and document inputs, and every reference-to-video endpoint bills input video seconds on top of output video seconds.&lt;/p&gt;

&lt;p&gt;Using &lt;code&gt;1,000 credits = $1.00 USD&lt;/code&gt;, reference images, reference audio, and document or web links add zero billable seconds. Any URL in &lt;code&gt;reference_video_urls&lt;/code&gt;, by contrast, has its duration probed at submission time and billed alongside &lt;code&gt;duration_seconds&lt;/code&gt; at the selected resolution tier: sending a 10-second reference video for a 5-second output bills 15 seconds total. Unreadable files or clips outside each model's duration bounds are rejected at submission before any credits leave the balance.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model endpoint&lt;/th&gt;
&lt;th&gt;Image refs&lt;/th&gt;
&lt;th&gt;Audio refs&lt;/th&gt;
&lt;th&gt;Video refs&lt;/th&gt;
&lt;th&gt;Resolution tiers (credits/s)&lt;/th&gt;
&lt;th&gt;Duration &amp;amp; min&lt;/th&gt;
&lt;th&gt;Notable request controls&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;POST /v1/seedance-2.5-spicy/reference-to-video&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1-30 (&lt;code&gt;300-6000px&lt;/code&gt; per side)&lt;/td&gt;
&lt;td&gt;1-10 (audio-only supported)&lt;/td&gt;
&lt;td&gt;1-10 (&lt;code&gt;&amp;lt;= 30s&lt;/code&gt; total)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;480p&lt;/code&gt;: 205.6, &lt;code&gt;720p&lt;/code&gt;: 462.4, &lt;code&gt;1080p&lt;/code&gt;: 1,137.2&lt;/td&gt;
&lt;td&gt;4-30s (min 823 cr)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;draft: true&lt;/code&gt;, `output_format: "mp4" \&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;{% raw %}&lt;code&gt;POST /v1/berry-1.0-pro-spicy/reference-to-video&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;1-10 (HTTP/HTTPS or base64)&lt;/td&gt;
&lt;td&gt;1-5 (audio-only supported)&lt;/td&gt;
&lt;td&gt;1-5 (&lt;code&gt;1-15s&lt;/code&gt; each, &lt;code&gt;&amp;lt;= 15s&lt;/code&gt; total, &lt;code&gt;&amp;lt;= 100MB&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;1080p&lt;/code&gt;: 270, &lt;code&gt;2k&lt;/code&gt;: 300, &lt;code&gt;4k&lt;/code&gt;: 345&lt;/td&gt;
&lt;td&gt;2-30s (min 540 cr)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;resolution&lt;/code&gt; required, &lt;code&gt;prompt_extend&lt;/code&gt;, &lt;code&gt;seed&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;POST /v1/w3.0-spicy/reference-to-video&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1-10 (HTTP/HTTPS or base64)&lt;/td&gt;
&lt;td&gt;1-5 (audio-only supported)&lt;/td&gt;
&lt;td&gt;1-5 (&lt;code&gt;1-15s&lt;/code&gt; each, &lt;code&gt;&amp;lt;= 15s&lt;/code&gt; total, &lt;code&gt;&amp;lt;= 100MB&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;480p&lt;/code&gt;: 75, &lt;code&gt;720p&lt;/code&gt;: 150, &lt;code&gt;1080p&lt;/code&gt;: 300&lt;/td&gt;
&lt;td&gt;2-30s (min 150 cr)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;file_url&lt;/code&gt; or &lt;code&gt;link_url&lt;/code&gt; (mutually exclusive), &lt;code&gt;prompt_extend&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;POST /v1/w3.0-pro-spicy/reference-to-video&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1-10 (HTTP/HTTPS or base64)&lt;/td&gt;
&lt;td&gt;1-5 (audio-only supported)&lt;/td&gt;
&lt;td&gt;1-5 (&lt;code&gt;1-15s&lt;/code&gt; each, &lt;code&gt;&amp;lt;= 15s&lt;/code&gt; total, &lt;code&gt;&amp;lt;= 100MB&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;1080p&lt;/code&gt;: 270, &lt;code&gt;2k&lt;/code&gt;: 300, &lt;code&gt;4k&lt;/code&gt;: 345&lt;/td&gt;
&lt;td&gt;2-30s (min 540 cr)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;file_url&lt;/code&gt; or &lt;code&gt;link_url&lt;/code&gt; (mutually exclusive), &lt;code&gt;prompt_extend&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two behavior flags trip production workers most often. First, on &lt;a href="https://hotapi.ai/en/models/seedance-2.5-spicy/reference-to-video" rel="noopener noreferrer"&gt;Seedance 2.5 Spicy reference-to-video&lt;/a&gt;, &lt;code&gt;generate_audio&lt;/code&gt; defaults to &lt;code&gt;true&lt;/code&gt;, and the upstream provider runs moderation on generated audio tracks after synthesis; for spicy visual scenes, an audio rejection fails the whole task and refunds credits without returning video, so pass &lt;code&gt;generate_audio: false&lt;/code&gt; whenever you supply your own audio or want silent output. Second, &lt;a href="https://hotapi.ai/en/models/w3.0-spicy/reference-to-video" rel="noopener noreferrer"&gt;Wan 3.0 Spicy&lt;/a&gt; and &lt;a href="https://hotapi.ai/en/models/w3.0-pro-spicy/reference-to-video" rel="noopener noreferrer"&gt;Wan 3.0 Pro Spicy&lt;/a&gt; pin &lt;code&gt;prompt_extend&lt;/code&gt; on when you pass &lt;code&gt;file_url&lt;/code&gt; (up to &lt;code&gt;100MB&lt;/code&gt; and 50 pages) or &lt;code&gt;link_url&lt;/code&gt;, whereas &lt;a href="https://hotapi.ai/en/models/berry-1.0-pro-spicy/reference-to-video" rel="noopener noreferrer"&gt;Berry 1.0 Pro Spicy&lt;/a&gt; skips document inputs and focuses on multi-media references up to 4K. For deeper trade-offs across tiers, see the &lt;a href="https://hotapi.ai/en/compare/seedance-2-5-vs-wan-3-0" rel="noopener noreferrer"&gt;Seedance 2.5 vs Wan 3.0 comparison&lt;/a&gt;, browse the full &lt;a href="https://hotapi.ai/en/compare" rel="noopener noreferrer"&gt;model comparisons index&lt;/a&gt;, or check every active endpoint in &lt;a href="https://hotapi.ai/en/docs/models" rel="noopener noreferrer"&gt;model reference docs&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why do reference image dimensions and upload TTLs break video tasks before rendering starts?
&lt;/h2&gt;

&lt;p&gt;Reference-to-video requests fail early if you pass unuploaded local files, images outside per-side pixel rules, or expired temporary upload URLs past their 24-hour TTL.&lt;/p&gt;

&lt;p&gt;On Seedance 2.5, every image in &lt;code&gt;reference_image_urls&lt;/code&gt; must stay between &lt;code&gt;300px&lt;/code&gt; and &lt;code&gt;6000px&lt;/code&gt; on each side. On Wan 3.0 and Berry 1.0 Pro, passing clips shorter than 1 second or larger than &lt;code&gt;100MB&lt;/code&gt; triggers validation failures, and &lt;code&gt;POST /v1/uploads&lt;/code&gt; rejects files whose sniffed magic bytes fail JPEG/PNG/WebP (&lt;code&gt;10 MB&lt;/code&gt; max, &lt;code&gt;8192px&lt;/code&gt; max side) or MP4/MOV/WebM/audio (&lt;code&gt;25 MB&lt;/code&gt; max) checks. Because &lt;code&gt;POST /v1/uploads&lt;/code&gt; URLs expire 24 hours after upload, never cache them as permanent character sheets across multi-day campaigns; upload right before submitting or store permanent anchor assets in your own object storage.&lt;/p&gt;

&lt;p&gt;When reference media includes human faces, HotAPI automatically registers trusted faces when an upstream video model requires it, capped at 200 distinct faces per organization. If a multi-tenant workspace hits &lt;code&gt;400 trusted_face_limit_reached&lt;/code&gt;, prune stale entries via &lt;code&gt;GET /v1/face-assets&lt;/code&gt; and &lt;code&gt;DELETE /v1/face-assets/{id}&lt;/code&gt;, as covered in the &lt;a href="https://hotapi.ai/en/docs/guides/uploads" rel="noopener noreferrer"&gt;HotAPI uploads documentation&lt;/a&gt; and the &lt;a href="https://hotapi.ai/en/playbooks/character-consistent-image-to-video-pipeline" rel="noopener noreferrer"&gt;character-consistent video pipeline playbook&lt;/a&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# 1. Upload a local character reference image (24h URL TTL)&lt;/span&gt;
&lt;span class="nv"&gt;UPLOAD_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;curl -sS -X POST https://api.hotapi.ai/v1/uploads \
  -H &lt;span class="s2"&gt;"Authorization: Bearer $HOTAPI_KEY"&lt;/span&gt; \
  -F &lt;span class="s2"&gt;"file=@./character-sheet.jpg"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; jq -r &lt;span class="s1"&gt;'.url'&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;

&lt;span class="c"&gt;# 2. Reference the uploaded image by index in a Wan 3.0 Pro 1080p render&lt;/span&gt;
curl -sS -X POST &lt;span class="s2"&gt;"https://api.hotapi.ai/v1/w3.0-pro-spicy/reference-to-video?webhook=https://app.example.com/hooks/hotapi"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Authorization: Bearer $HOTAPI_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Idempotency-Key: shot_04_take_1"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s2"&gt;"{
    \"reference_image_urls\": [\"$UPLOAD_URL\"],
    \"prompt\": \"[Slow dolly in] Image 1 walks across a rain-slicked neon crosswalk, warm amber reflection on asphalt, steady 35mm lens.\",
    \"duration_seconds\": 6,
    \"resolution\": \"1080p\",
    \"ratio\": \"16:9\",
    \"generate_audio\": false
  }"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How does beat-planned prompt timing prevent subject morphing across 8-to-30-second clips?
&lt;/h2&gt;

&lt;p&gt;Breaking an 8-to-30-second clip into timestamped 2.5-to-5-second action beats prevents the diffusion backbone from collapsing three unrelated movements into limb distortion or abrupt camera whips.&lt;/p&gt;

&lt;p&gt;Packing four actions into a 6-second prompt forces rapid pose interpolation between frames. Instead, anchor camera movement and lighting in a bracketed opening clause like &lt;code&gt;[Static medium shot]&lt;/code&gt; or &lt;code&gt;[Slow tracking shot]&lt;/code&gt;, divide the clip into explicit windows (&lt;code&gt;Beat 1 (0-4s)&lt;/code&gt; and &lt;code&gt;Beat 2 (4-8s)&lt;/code&gt;), and place sound direction at the tail when &lt;code&gt;generate_audio&lt;/code&gt; is enabled. On Wan 3.0, address inputs explicitly per type (&lt;code&gt;Image 1&lt;/code&gt;, &lt;code&gt;Video 1&lt;/code&gt;) so the model binds motion and appearance to the right asset. You can test beat spacing and credit totals before coding with the &lt;a href="https://hotapi.ai/en/tools/video-prompt-beat-planner" rel="noopener noreferrer"&gt;video prompt beat planner&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;On &lt;code&gt;seedance-2.5-spicy&lt;/code&gt;, pair beat-planned timing with a two-stage draft flow. Submitting with &lt;code&gt;draft: true&lt;/code&gt; and &lt;code&gt;resolution: "480p"&lt;/code&gt; (or omitting &lt;code&gt;resolution&lt;/code&gt;, which defaults to &lt;code&gt;480p&lt;/code&gt;; any higher resolution is rejected with &lt;code&gt;draft: true&lt;/code&gt;) lets you inspect pacing and framing at &lt;code&gt;205.6 credits/s&lt;/code&gt; instead of &lt;code&gt;1,137.2 credits/s&lt;/code&gt;. A 480p draft is not discounted, so its savings come purely from catching broken framing before committing to 1080p. Once a draft succeeds, pass its task ID to &lt;code&gt;POST /v1/seedance-2.5-spicy/draft-to-video&lt;/code&gt; within 7 days; the final reuses the draft's prompt, references, duration, ratio, seed, and audio flags verbatim, and allows switching &lt;code&gt;output_format&lt;/code&gt; to &lt;code&gt;"mov"&lt;/code&gt; for post-production grading as documented in the &lt;a href="https://hotapi.ai/en/models/seedance-2.5-spicy/draft-to-video" rel="noopener noreferrer"&gt;Seedance 2.5 draft-to-video spec&lt;/a&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Promote a succeeded 480p draft task into a 1080p 10-bit HEVC MOV final&lt;/span&gt;
curl -sS -X POST &lt;span class="s2"&gt;"https://api.hotapi.ai/v1/seedance-2.5-spicy/draft-to-video?webhook=https://app.example.com/hooks/hotapi"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Authorization: Bearer $HOTAPI_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Idempotency-Key: finalize_task_8sd9f7aQ2"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{
    "draft_task_id": "task_8sd9f7aQ2",
    "output_format": "mov"
  }'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  When should a worker rely on HMAC webhooks instead of polling GET /v1/tasks/{id}?
&lt;/h2&gt;

&lt;p&gt;Any generation job taking longer than 10 seconds should use &lt;code&gt;?webhook=&lt;/code&gt; push callbacks as the primary completion path, paired with a 60-second background sweeper calling &lt;code&gt;GET /v1/tasks?status=active&amp;amp;fields=summary&lt;/code&gt; or &lt;code&gt;GET /v1/tasks/{id}&lt;/code&gt; as a fallback.&lt;/p&gt;

&lt;p&gt;HotAPI splits rate limits across two independent 60-second sliding windows: &lt;code&gt;60 requests/minute&lt;/code&gt; by default for generation submissions and &lt;code&gt;600 requests/minute&lt;/code&gt; (&lt;code&gt;10x&lt;/code&gt; base RPM) for &lt;code&gt;GET /v1/tasks&lt;/code&gt; and &lt;code&gt;GET /v1/tasks/{id}&lt;/code&gt; reads. Polling a few active jobs at a 5-second interval will not eat into submission capacity, yet scaling to hundreds of concurrent renders wastes worker cycles if each job opens its own polling loop. Passing &lt;code&gt;?webhook=https://...&lt;/code&gt; triggers a signed &lt;code&gt;POST&lt;/code&gt; on &lt;code&gt;task.succeeded&lt;/code&gt;, &lt;code&gt;task.failed&lt;/code&gt;, or &lt;code&gt;task.cancelled&lt;/code&gt; and retries non-2xx responses up to five additional times (&lt;code&gt;+1m&lt;/code&gt;, &lt;code&gt;+5m&lt;/code&gt;, &lt;code&gt;+30m&lt;/code&gt;, &lt;code&gt;+2h&lt;/code&gt;, &lt;code&gt;+12h&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;Four webhook handler checks prevent silent production bugs. Read the raw HTTP body bytes before any JSON parser reformats whitespace, reject timestamps older than 300 seconds, compare the &lt;code&gt;v1&lt;/code&gt; HMAC-SHA256 hex digest of &lt;code&gt;&amp;lt;timestamp&amp;gt;.&amp;lt;raw_body&amp;gt;&lt;/code&gt; in constant time against your org-wide &lt;code&gt;HOTAPI_WEBHOOK_SECRET&lt;/code&gt;, and deduplicate deliveries on &lt;code&gt;HotAPI-Event-Id&lt;/code&gt; (or &lt;code&gt;id&lt;/code&gt; in the signed body). Always reply with a &lt;code&gt;2xx&lt;/code&gt; status within 10 seconds and copy &lt;code&gt;output.assets[].url&lt;/code&gt; into durable storage before &lt;code&gt;expires_at&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Full signature headers live in the &lt;a href="https://hotapi.ai/en/docs/guides/webhooks" rel="noopener noreferrer"&gt;HotAPI webhooks guide&lt;/a&gt;. For queue worker code, refer to the &lt;a href="https://hotapi.ai/en/integrations/fastapi-webhooks" rel="noopener noreferrer"&gt;FastAPI webhook integration blueprint&lt;/a&gt; inside the &lt;a href="https://hotapi.ai/en/integrations" rel="noopener noreferrer"&gt;integrations hub&lt;/a&gt;, along with the &lt;a href="https://hotapi.ai/en/playbooks/async-webhook-worker-queue" rel="noopener noreferrer"&gt;async webhook worker queue playbook&lt;/a&gt; in the &lt;a href="https://hotapi.ai/en/playbooks" rel="noopener noreferrer"&gt;engineering playbooks index&lt;/a&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;hashlib&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;hmac&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;json&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;time&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;fastapi&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;FastAPI&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Header&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;HTTPException&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;

&lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;FastAPI&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;os&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;environ&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"HOTAPI_WEBHOOK_SECRET"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="no"&gt;PROCESSED_EVENTS&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;set&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;  &lt;span class="c1"&gt;# Replace with an atomic DB unique constraint in prod.&lt;/span&gt;

&lt;span class="nd"&gt;@app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/hooks/hotapi"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;receive_task_webhook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;hotapi_signature&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;str&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;default&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;hotapi_event_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;str&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Header&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;default&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="n"&gt;raw_body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;body&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="n"&gt;parts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;dict&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"="&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;hotapi_signature&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;","&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="s2"&gt;"="&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;t_str&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;v1&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"t"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"v1"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="n"&gt;t_str&lt;/span&gt; &lt;span class="ow"&gt;or&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="n"&gt;v1&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;HTTPException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;detail&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"Malformed HotAPI-Signature header"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="k"&gt;try&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;timestamp&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t_str&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;except&lt;/span&gt; &lt;span class="nc"&gt;ValueError&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;exc&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;HTTPException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;detail&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"Invalid timestamp"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;exc&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="nb"&gt;abs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;time&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;time&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;timestamp&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;300&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;HTTPException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;401&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;detail&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"Stale webhook timestamp"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="n"&gt;signed_payload&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"{t_str}."&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"utf-8"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;raw_body&lt;/span&gt;
    &lt;span class="n"&gt;expected_v1&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;hmac&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="no"&gt;WEBHOOK_SECRET&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"utf-8"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;signed_payload&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;hashlib&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sha256&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;hexdigest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="n"&gt;hmac&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;compare_digest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;v1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;expected_v1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;HTTPException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status_code&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;401&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;detail&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"Signature mismatch"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="n"&gt;envelope&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;loads&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;raw_body&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;dedupe_key&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;envelope&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="ow"&gt;or&lt;/span&gt; &lt;span class="n"&gt;hotapi_event_id&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;dedupe_key&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="no"&gt;PROCESSED_EVENTS&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"deduped"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="no"&gt;PROCESSED_EVENTS&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dedupe_key&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;task&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;envelope&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"data"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;task&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"succeeded"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;asset_urls&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;asset&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;asset&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;task&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"output"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"assets"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
        &lt;span class="c1"&gt;# Enqueue durable copy to your own S3/R2 bucket before task["expires_at"].&lt;/span&gt;
        &lt;span class="k"&gt;print&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"Task {task['id']} succeeded with {len(asset_urls)} asset(s)"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;elif&lt;/span&gt; &lt;span class="n"&gt;task&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"failed"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"cancelled"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;print&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"Task {task['id']} ended: {task.get('error')}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How should production teams sequence a reference-to-video rollout?
&lt;/h2&gt;

&lt;p&gt;Start on a dedicated development organization with 480p &lt;code&gt;w3.0-spicy&lt;/code&gt; or &lt;code&gt;draft: true&lt;/code&gt; Seedance 2.5 submissions, verify HMAC raw-body checks against a public HTTPS tunnel, and promote only after your worker survives duplicate webhook deliveries and &lt;code&gt;429&lt;/code&gt; backoffs.&lt;/p&gt;

&lt;p&gt;Keep submission requests strictly server-side so &lt;code&gt;HOTAPI_KEY&lt;/code&gt; never enters client bundles, run a 60-second sweeper over non-terminal rows older than 90 seconds, and benchmark side-by-side quality between &lt;a href="https://hotapi.ai/en/models/seedance-2.5-spicy" rel="noopener noreferrer"&gt;Seedance 2.5 Spicy&lt;/a&gt; and &lt;a href="https://hotapi.ai/en/models/w3.0-spicy" rel="noopener noreferrer"&gt;Wan 3.0 Spicy&lt;/a&gt; on identical reference sets before locking your default production tier.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>api</category>
      <category>typescript</category>
      <category>python</category>
    </item>
  </channel>
</rss>
