タスクと結果

冪等キーで非同期タスクを安全に送信し、メディアをアップロードし、状態を確認して結果をダウンロードします。

タスクを送信（非同期）

同期呼び出しはありません。POST /api/v1/jobs は入力を検証し、クレジットから料金を予約してすぐに応答します。新しいタスクは 202、冪等な再試行が以前のものと一致した場合は 200 です。

ヘッダー	値	備考
`Authorization`	`Bearer <API key>`	または x-api-key でキーを送信します。
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	必須。まったく同じリクエストを再試行する場合のみ再利用してください。

フィールド	型	必須	備考
`model`	`string`	必須	カタログのモデル slug。
`input`	`object`	必須	モデルの入力スキーマのフィールド。
`expectedPriceMicros`	`integer`	任意	ユーザーに表示した料金。一致しない場合は課金前に 409 PRICE_CHANGED が返されます。

安全に再試行

ネットワーク障害後に再試行するときは、同じ Idempotency-Key とボディを使ってください。入力を変える場合は新しいキーを使います。入力を変えて同じキーを再利用すると 409 IDEMPOTENCY_CONFLICT が返されます。

メディアをアップロード

画像・動画フィールドには、公開 HTTPS URL または media:<uuid> 参照を指定します。ローカルファイルは先にアップロードしてください：

POST /api/v1/media

curl -X POST https://api.hermes-ai.net/api/v1/media \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @input.png
# → { "reference": "media:<uuid>", ... }  Use the reference in an image or video field.

タスクの結果を取得

ポーリング GET /api/v1/jobs/{id} 数秒ごとにポーリングし、終了状態で停止します。reconciliation_required のタスクを自動で再送信しないでください。

ステータス	終了状態	意味
`queued`	いいえ	受け付け済みで、ワーカーを待っています。
`submitting`	いいえ	モデルプロバイダーに送信中です。
`running`	いいえ	モデルが生成中です。
`succeeded`	はい	完了しました。結果は assets にあります。
`failed`	はい	結果なしで終了しました。予約は解放されます。
`reconciliation_required`	はい	The result is being verified. Keep the task ID and do not resubmit automatically.

フィールド	型	備考
`id`	`string`	Hermes AI のタスク ID。ポーリングに使用します。
`model`	`string`	モデル slug。
`status`	`string`	タスクのステータスを参照。
`errorCode`	`string \| null`	タスクが失敗した場合や確認が必要な場合に設定されます。
`priceMicros`	`integer`	受付時に確定した見積もり（USD マイクロ単位）。
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	ISO 8601 形式のタイムスタンプ。
`assets[]`	`array`	{ id, type, url?, text? }。url は同一オリジンの /api/v1/results/<uuid> リンクです。
`replayed`	`boolean`	送信時のみ。冪等な再試行が一致した場合は true。

結果のアセットには、テキストまたは同一オリジンの /api/v1/results/<uuid> URL が含まれます。ファイルは同じ認証情報（media:read 権限）でダウンロードしてください。GET /api/v1/jobs は最新 100 件のタスクを返します。