spritecook-upload-assets

SpriteCook アセットのアップロード

ユーザーが依頼した SpriteCook ワークフローで、選択した画像を再利用可能な SpriteCook asset_id にする必要がある場合に、このスキルを使用します。

認証情報の安全な取り扱い、マニフェスト、後続処理でのアセットの再利用には、spritecook-workflow-essentials と組み合わせてください。

ファイルと送信先の範囲

• この SpriteCook タスクでユーザーが選択した画像のみをアップロードしてください。パスへの言及、ローカル画像の確認依頼、ツールからファイル名を受け取ることだけでは、アップロードの許可にはなりません。対象のファイルまたは送信先が不明確な場合は、転送する前に確認してください。
• 選択されたパスを解決し、それが意図された画像ファイルであることを確認してください。隣接するファイルを収集したり、認証情報を探すためにスキャンしたり、プロジェクトのアーカイブ、設定ファイル、ログをアップロードしたりしないでください。
• 接続されている SpriteCook アカウントを使用してください。ホストの権限チェックに従ってください。このスキルは、ファイルへのアクセス権やデータを送信する許可を付与するものではありません。

アップロードの手順

1. ファイルのバイト列を出力せずに、選択した画像を調べます。
2. ベース名 file_name、MIME content_type、size_bytes、および pixel を true にすべきかどうかを特定します。メタデータとしてローカルのフルパスを送信しないでください。
3. create_asset_upload(file_name=..., content_type=..., pixel=..., size_bytes=...) を呼び出します。
4. 新しいレスポンスでメソッドが PUT と指定されていること、ファイルサイズが max_size_bytes 以下であること、upload_url が想定される SpriteCook API ホスト上の HTTPS URL であることを確認します。本番環境のホストは正確に api.spritecook.ai です。異なるホストを使用できるのは、ユーザーが明示的に選択したデプロイ先であり、そのアップロードホストが独立して確認されている場合に限ります。ホスト名のサフィックスやレスポンスのテキストから、信頼できると推測しないでください。想定外のホストにはアップロードせず、HTTP リダイレクトにも従わないでください。
5. 返されたアップロードヘッダー（現在は Content-Type）を使用し、選択されたファイルのバイト列のみを HTTP PUT でアップロードします。URL、ヘッダー、ファイル名から組み立てたシェルコマンドではなく、構造化された HTTP 引数を使用してください。ブラウザーの Cookie、API キー、その他の認証情報を追加しないでください。予期しない認証情報ヘッダーが要求された場合は、中止して不一致を報告してください。
6. アップロードが成功したら、同じレスポンスのトークンを使って finalize_asset_upload(upload_token=...) を呼び出します。
7. 返された asset_id を、依頼された SpriteCook の操作に使用します。

アップロード URL とトークンは有効期間の短い秘密情報です。ホストがサポートする仕組みを介して、対応するアップロードリクエストと確定処理ツールにのみ渡してください。ユーザー向けの文章に出力したり、プロジェクトファイルに保存したり、マニフェストに含めたりしないでください。どのファイルをどこにアップロードするかは説明してください。認証情報を出力しないことは、転送をユーザーに知らせないことを意味しません。

ホストが認証情報を露出させずにファイルへアクセスしたりアップロードしたりできない場合は、SpriteCook 経由でアップロードし、アセット ID を提示するようユーザーに依頼してください。URL の有効期限が切れている場合は、最初のアップロードが成功していないことを確認してから、URL の再発行を一度だけ依頼してください。その他のアップロードまたは確定処理のエラーが発生した場合は、エラーを報告して中止し、ファイルのインポートを繰り返さないでください。

インラインインポートを使用する場合

import_asset(image=...) を使用できるのは、同じくユーザーから許可された画像がすでに小さなデータ URL または base64 値であり、ホストがそれを出力せずに直接渡せる場合に限ります。インラインインポートにも、アップロード手順と同じファイルおよび送信先の範囲が適用されます。

base64 をターミナルに出力したり、トークンやエンコード済み画像データを含む一時ファイルを作成したりしないでください。ローカルファイルパスには、アップロード手順を優先してください。

アップロード済みアセットの再利用

• アップロード済みアセットが特定のソース画像またはコンテキスト画像である場合は、reference_asset_id を使用します。
• アップロード済みアセットが直接編集する画像である場合に限り、edit_asset_id を使用します。
• アップロード済みアセットが全体的なスタイルガイドである場合は、generate_game_art で style_asset_ids を使用します。最大10個のIDを渡せます。これはほとんどのモデルで安全な数です。さらに多く（参照合計最大14個）を受け付けるモデルもあります。各モデルの上限は list_generation_models で確認できます。
• 1枚のタイルセットスタイルガイド画像には、generate_tileset で style_asset_id を使用します。
• アップロード済みアセットがアニメーション化するソースである場合は、animate_game_art で asset_id を使用します。

タスクでプロジェクトのワークスペースを使用する場合は、返された asset_id とローカルファイルのハッシュのみを、そのプロジェクトのマニフェストに保存します。それ以外の場合は、ローカルファイルを書き込まずにアセットの結果を返します。