AI画像・動画の保存：一時アップロードURL、短期間の生成結果、確実なAPIでの受け渡し

検閲なしのAI画像・動画サービスを開発する場合、保存設計を決める事実は三つあります。アップロードした参照ファイルは1日で期限切れになります。API、SDK、Playgroundのタスクで生成したメディアは約14日保存されます（Studioの短編動画メディアには、約60日という別の上限があります）。受け取るダウンロードリンクは、どれも約20分しか使えません。これらはすべて上限です。アカウント全体またはリクエストごとに短縮することはでき、完了したタスクの内容は必要なときに削除できますが、どの設定でも上限を延ばすことはできません。

確実な流れは、短時間有効なチケットで直接アップロードし、ファイルを確定し、非公開のspicy://参照で非同期タスクを送信し、完了後に結果のリンクを取得して、自分で管理するストレージへコピーするか、意図的に期限切れにすることです。顧客のアップロードを公開バケットに置いたり、返されたダウンロードURLを恒久的なものとして保存したりしないでください。

SpicyAPIへの参照ファイルのアップロードは無料です。それを使う生成タスクには別途料金がかかります。既存の結果のダウンロードリンクを更新しても、生成を再実行したり再購入したりすることにはなりません。新しい生成を試すとモデルの料金が別途かかり、自分のバケットに置くコピーの保存、リクエスト、転送には、ストレージ事業者の料金が適用されます。

顧客に保存期間を約束する前に、実際に受け付けられた期限を確認してください。設定は保存期間のドキュメントで説明しています。ローカルコピーの実用例は、一時的なAIメディアを長期利用できる製品アセットにする方法にあります。

まずPlaygroundで試す

1. z-imageのテキストから画像ページを開き、WorkbenchのFormでPromptを入力し、Aspect ratioを選び、Run modelを選択します（先にログインしてください。この画像生成は通常の有料処理です）。Previewで確認し、Downloadで保存します。
2. ConsoleでLogsを開き、そのタスクを見つけて出力の保存期間を確認します。
3. Data protection、Retentionの順に開き、四つの保存期間を確認して必要なものを短縮します。
4. 自分のコピーを確保したら、完了したタスクでDestroy outputsを選び、内容を削除します。

SpicyAPIが保存するものと保存期間

自分で期間を短縮する、または内容を削除する

1. アカウントの保存期間。 ConsoleのData protectionページのRetentionには、独立した四つの保存期間があります。

アップロードファイルの保存期間には、重要な制限が三つあります。

• Delete when the job ends：そのアップロードを使うすべてのタスクが最終状態に達すると、通常は1分以内に削除されます。削除済みの参照を使って新たに生成するには、もう一度アップロードする必要があります。
• 既存ファイルのみ：この切り替えは設定を保存した時点で存在するファイルに適用されます。後からアップロードしたファイルは、現時点では確定処理の応答に示される標準の1日期限を維持します。
• 1時間と24時間の選択肢：現時点では変更されません。アップロードは返されたexpiresAtまで利用できます。

短縮する前の注意：短い設定は、すでに実行したタスクにもさかのぼって適用される場合があります。たとえばPrompt textを1時間または24時間に設定すると、Generated resultsが14日のままでも、完了から1日を超えたすべてのタスクのプロンプト本文と生成結果が消去されます。削除済みの内容は復元できません。残したいものは先にダウンロードしてください。設定を長くしても、影響するのは今後の保存だけです。

2. リクエストごとの指定。タスク作成時にX-Spicy-Retentionヘッダーを秒数で送信します。保存期間のドキュメントにリクエスト例があります。実際の保存期間は、リクエスト指定、アカウント設定、プラットフォーム上限のうち最短のものです。要求した期間を約束するのではなく、タスクに返された期限を確認してください。

配信や保存済みライブラリを約束するサービスでは、即時削除を使わないでください。コピーの完了前に結果が削除される可能性があります。配信後に復旧のための余裕を残してください。

3. 完了したタスクの内容を削除する。必要なものをコピーした後、または顧客から削除を求められたときは、そのタスクの創作内容を削除します。

Consoleでは、Logs内のタスクのDestroy outputsが同じ操作に当たります。三つのルールがあります。

• 完了したタスクのみ。PurgeはtaskId単位で冪等であり、Idempotency-Keyは不要です。生成のキャンセルや料金の返金は行わず、billingRetainedはtrueのままです。
• 削除は予定されます。contentStateはpurgedになりますが、通常1分以内にクリーンアップが終わるまでmediaDeletionPendingはtrueのままです。顧客にデータがなくなったと伝える前に、完了を確認してください。
• presentという応答では何も削除されていません。削除完了と報告せず、応答と保持設定を調べてください。

保存期間によって内容が削除された場合、contentStateはexpired、自分で削除した場合はpurgedです。タスクの状態のexpiredは、まったく別の意味で、生成がタイムアウトし、何も生成されなかったことを示します。再試行が役立つのは後者だけです。

参照ファイルを送信する

参照画像、参照動画、参照音声ファイルをタスクに渡す方法は三つあります。公開HTTPS URLは、ファイルそのものを返す必要があります。共有ページ（クラウドドライブ、写真アルバム、ソーシャル投稿）へのリンクはウェブページを返すため、タスクはinvalid_assetで失敗します。その場合はファイルをダウンロードしてアップロードしてください。小さい画像（最大1 MiB）はbase64のデータURIとしてインラインで渡せます。非公開または大きいファイルはSDK、CLI、Playgroundでアップロードし、タスク用の非公開spicy://参照を取得してください。

アップロード上限は、JPEG、PNG、WebP、GIFが10 MiB、WAV、MP3、WebM、MP4、MOVが90 MiBおよび600秒です。モデル側の上限がこれより小さい場合もあります。1日の期限後に入力が再び必要になるなら、元ファイルを保存してください。バックエンドはアップロードの許可と所有者の記録だけを行えばよく、クライアントがデータを直接送れます。アップロードは無料で、生成は別途購入します。メディアのドキュメントに手順があります。

結果を取得し、コピーするか期限切れにする

原稿と風景のフレームが一つの投影シーンに集まっています。

新しいリクエストごとに独自の冪等キーを使って送信し、タスクIDを保持して、ポーリングまたはコールバックで結果を取得します。準備済みのアセットには署名付きのurlが含まれます。APIキーなしで取得し、User-AgentにはMozilla/5.0などを指定してください。CDNはPythonのurllibの標準エージェントを403で拒否するためです。この応答はリンクの期限切れを意味しません。succeededのタスクにもpendingのアセットが残ることがあるため、URLの準備ができるまで確認を続けてください。期限切れのリンクは保存期間内なら更新できます。メディアのドキュメントで方法を説明しています。

アセットの三つの状態を明示的に扱うとよいでしょう。

テキストのみのモデルにはassetsが一切ありません。また、output.textのテキストも同じ予定で消去されるため、ファイルがあると考える前に内容を読み取ってください。

保存失敗時に料金を請求しない例外は、タスクのすべての出力が初期保存できなかった場合に適用されます。古いアセットがunavailableであるだけでは、返金対象とは判断できません。元のタスクの精算を確認してください。

コールバックには、プロンプトと署名付きの結果リンクが含まれます。エンドポイント、リバースプロキシ、エラー追跡ツール、ログ処理系にも、SpicyAPI自身が予定に従って消去するデータが届きます。アクセスログにコールバック本文を残さないようにし、コピーはワーカーで行ってください。署名確認、重複排除、再試行はWebhookのドキュメントにあります。

• ライブラリ、共有、後日の編集を約束するサービス：成功を確認したら直ちに、自分で管理する非公開ストレージへ結果をストリーミング転送し、独自のアセットIDを記録します。プラットフォームのコピーを削除したい場合は、その後Purgeを呼びます。大きい動画を全体ごとメモリに読み込まず、ストリーミングしてください。転送先への書き込みはタスクとアセットの組み合わせで冪等にします。
• 一度限りの配信：コピーしません。結果を表示し、顧客に有効期間を伝え、保存期間または短いX-Spicy-Retentionによって削除します。

ユーザーがアップロードした参照ファイルは、マーケティング素材ではありません。また、生成が成功しても、公開への同意が得られたわけではありません。自分のコピーの完了を確認してから「顧客が保存済み」と記録してください。

問題が起きた場合

創作内容を残さず、役に立つログを保つ

次の経路に意図しないコピーがないか確認してください。

• エラー報告とアクセスログ：プロンプト、チケット、署名付きリンクを除去し、メディア関連ルートの本文の記録を避けます。
• 分析とキュー：URLやファイル名の代わりに、内容を推測できない操作ID、タスクID、アセットIDを使います。配信不能メッセージの保管先も同様です。
• サポート向けのエクスポートと公開配信：スクリーンショット、ページのメタデータ、メールを確認します。アクセス確認後に新しいリンクを発行する、認証が必要なページへ顧客を案内します。
• 自分のストレージとバックアップ：独自の削除方針を適用します。期限切れのリンクで、すでに誰かがダウンロードしたファイルを取り消すことはできません。

保存設定では約束できないこと

• モデルはプロンプトを見ます。リクエストを実行するモデルはプロンプトを平文で受け取ります。SpicyAPIの設定が制御するのは、SpicyAPI自身の保存期間だけです。送る必要のないものは送らないでください。
• Purgeは非同期の削除要求です。返された内容の状態とメディア削除の完了を確認してください。ストレージのライフサイクル処理とバックアップの入れ替えには、別々の期間があります。自分でコピーしたファイルとバックアップにも、それぞれ削除操作が必要です。課金記録はいずれの場合も残ります。

契約に別の保存期間を明記する必要があるなら、ドキュメントのページから推測するのではなく、署名前に相談してください。

よくある質問

一時アップロードURLを生成リクエストの画像URLとして使えますか？

使えません。アップロードURLは直接書き込むことだけを許可します。アップロードして確定し、確定済みのspicy:// URIを、現在のモデルスキーマでアップロード用と指定されているフィールドに入れてください。

生成した動画をSpicyAPIで14日より長く保存できますか？

API、SDK、Playgroundの結果はできません。上限は約14日です。Studioの短編動画メディアには約60日という別の上限があります。長く利用するには、成功後に自分のストレージへコピーしてください。

Purgeでタスクの料金は返金されますか？

返金されません。Purgeは内容だけを削除し、料金とタスク記録は残ります。

Webhookでポーリングを完全に置き換えられますか？

主な経路として使えますが、配信漏れを確認するための範囲を限定した照合処理を用意してください。ハンドラーは配信のrequest_idとタスクIDをキーにします。

結果のリンクをメールに入れてもよいですか？

避けてください。メールは短時間のリンクが失効した後も転送・保管されます。アクセスを確認して新しいリンクを発行する、認証が必要なページへ顧客を案内してください。

顧客が保存済みの結果を削除したら、何をすべきですか？

自分のコピーとその配信経路を削除または無効化し、実施した記録を残してください。プラットフォームのコピーは独自の予定に従います。早く削除する必要があればDestroy outputsを使います。

既存のタスクをコードで確認する

spicyapiをインストールし、SPICY_API_KEYとTASK_IDを設定して、以下の読み取り専用の確認を実行します。生成の作成や内容の削除は行いません。

import json
import os
from spicyapi import SpicyClient

client = SpicyClient()
task = client.get_task(os.environ["TASK_ID"])
print(json.dumps({"taskId": task["taskId"], "state": task["state"],
    "contentState": task.get("contentState"), "retention": task.get("retention"),
    "mediaDeletionPending": task.get("mediaDeletionPending")}, indent=2))

リクエスト設定と削除の仕様は、保存期間のリファレンスにあります。

呼び出しをAgentに任せる

すでにタスクIDがある場合は、ストレージ確認を任せられます。新しい生成は必要ありません。

• CLI：npx @spicyapi/cli tasks get "$TASK_ID"で現在の期限を読み取ります。CLIガイドを参照してください。
• MCP：spicyapi_task_getにそのタスクの確認を依頼します。spicyapi_task_purgeは内容の削除を明示的に承認した後だけ使ってください。MCPガイドに確認の手順があります。
• Skill：npx skills add spicyapi-ai/spicy-skillの実行後、$spicyapiにタスクの保存期間を確認し、何が期限切れになるか説明するよう依頼します。Skillガイドを参照してください。