چرا باید منتظر پر شدن assets بمانم و نه فقط succeeded؟

آینهسازی خروجی چند ثانیه بعد از اتمام کار انجام میشود (معمولاً ۵ تا ۳۰ ثانیه). لینکهای assets روی دامنهٔ هرمز هستند و ۷ روز معتبر میمانند؛ لینک منبع خیلی زود منقضی میشود.

هزینهٔ prediction چطور محاسبه میشود؟

هر مدل قیمت ثابتِ هر اجرا دارد که در کاتالوگ مدلها نمایش داده میشود. مبلغ قبل از اجرا از اعتبار بلوکه و پس از پایان تسویه میشود؛ اگر کار لغو یا خطا شود، مبلغ آزاد میگردد.

Predictions، تصویر، ویدیو و صدا

مدل‌های تولید تصویر، ویدیو و صدا ناهمگام اجرا می‌شوند: با POST /v1/predictions کار را بسازید، با GET /v1/predictions/{id} تقریباً هر ۲ ثانیه یک‌بار وضعیت را بپرسید، و وقتی status برابر succeeded و آرایهٔ assets پر شد، فایل را از لینک assets دانلود کنید. خروجی‌ها روی سرورهای هرمز آینه می‌شوند تا از داخل ایران سریع و پایدار دانلود شوند.

POST/v1/predictionsاحراز هویت Bearer

Create a prediction

Start an async prediction job on an image/video model (image generation, video, audio, etc.). Returns immediately with a prediction ID that you poll until completion.

The async flow:

POST /v1/predictions → Get prediction id (status: starting)
GET /v1/predictions/{id} → Poll until succeeded AND assets populated
GET /v1/assets/{asset_id} → Download the output file

پارامترها

فیلد	in	نوع	توضیح
`Idempotency-Key`	header	string	Optional deduplication token (any string up to 200 characters). How it works: Same key + same request body → cached response replayed (safe retry) Same key + different body → `409 CONFLICT` error Keys expire after 24 hours When to use: Add this header when you want to safely retry a request after a network timeout without risking a duplicate operation.

بدنه درخواستالزامی

فیلد	نوع	توضیح
`version`الزامی	string	Model identifier. Two formats: Bare name (`owner/name`) uses the latest approved version (e.g., `black-forest-labs/flux-pro`) Pinned (`owner/name:hash`) uses a specific model version Must be an admin-approved model. Unapproved models return `400 MODEL_NOT_APPROVED`. نمونه: `black-forest-labs/flux-pro`
`input`الزامی	object	Model-specific input parameters. Each model accepts different inputs: check `GET /v1/models` for the `input_fields` of each model. Common fields for image models: `prompt` (string): Text description of the desired image `width` / `height` (integer): Output dimensions `num_outputs` (integer): Number of images to generate `guidance_scale` (number): How closely to follow the prompt
`webhook`	string (uri)	Optional webhook URL to receive prediction status updates. Hormouz normally handles webhooks internally for billing; only set this if you need a copy of the events.
`webhook_events_filter`	array of string	Filter which events trigger your webhook. Values: `start`, `output`, `logs`, `completed`.

نمونه

curlPythonJavaScriptGo

# 1. Create the prediction
curl https://api.hormouz.net/v1/predictions \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "black-forest-labs/flux-schnell",
    "input": {"prompt": "a sunset over mountains"}
  }'

# 2. Poll until "status" is "succeeded" AND "assets" is non-empty
curl https://api.hormouz.net/v1/predictions/PREDICTION_ID \
  -H "Authorization: Bearer ng-YOUR_API_KEY"

import requests, time

BASE = "https://api.hormouz.net/v1"
H = {"Authorization": "Bearer ng-YOUR_API_KEY"}

r = requests.post(f"{BASE}/predictions", headers=H, json={
    "version": "black-forest-labs/flux-schnell",
    "input": {"prompt": "a sunset over mountains"},
})
pred = r.json()

while True:
    pred = requests.get(f"{BASE}/predictions/{pred['id']}", headers=H).json()
    if pred["status"] == "succeeded" and pred.get("assets"):
        break
    if pred["status"] in ("failed", "canceled"):
        raise RuntimeError(pred.get("error"))
    time.sleep(2)

img = requests.get(pred["assets"][0]["url"], headers=H).content
open("output.webp", "wb").write(img)

const BASE = "https://api.hormouz.net/v1";
const H = { Authorization: "Bearer ng-YOUR_API_KEY", "Content-Type": "application/json" };

let pred = await (await fetch(BASE + "/predictions", {
  method: "POST",
  headers: H,
  body: JSON.stringify({
    version: "black-forest-labs/flux-schnell",
    input: { prompt: "a sunset over mountains" },
  }),
})).json();

while (pred.status !== "succeeded" || !pred.assets?.length) {
  if (pred.status === "failed" || pred.status === "canceled") throw new Error(pred.error);
  await new Promise((r) => setTimeout(r, 2000));
  pred = await (await fetch(BASE + "/predictions/" + pred.id, { headers: H })).json();
}
console.log(pred.assets[0].url);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

type prediction struct {
	ID     string `json:"id"`
	Status string `json:"status"`
	Assets []struct {
		URL string `json:"url"`
	} `json:"assets"`
}

func call(method, url string, body []byte) prediction {
	req, _ := http.NewRequest(method, url, bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var p prediction
	json.NewDecoder(resp.Body).Decode(&p)
	return p
}

func main() {
	body, _ := json.Marshal(map[string]any{
		"version": "black-forest-labs/flux-schnell",
		"input":   map[string]string{"prompt": "a sunset over mountains"},
	})
	p := call("POST", "https://api.hormouz.net/v1/predictions", body)
	for p.Status != "succeeded" || len(p.Assets) == 0 {
		if p.Status == "failed" || p.Status == "canceled" {
			panic(p.Status)
		}
		time.Sleep(2 * time.Second)
		p = call("GET", "https://api.hormouz.net/v1/predictions/"+p.ID, nil)
	}
	fmt.Println(p.Assets[0].URL)
}

پاسخ‌ها

201

Prediction created. Poll GET /v1/predictions/{id} for status.

400

The request body or query parameters are invalid. Check the error.code and error.message fields for details. Codes the gateway emits at 400:

BAD_REQUEST: generic malformed JSON / missing required field.
INVALID_TOOLS: the tools array, plugins field, or model's :online suffix uses an unsupported shape. The response names the offender and links to the supported form. See the dedicated InvalidTools response below for the three triggers and migration hints.
UNSUPPORTED_TOOL: a built-in tool (file_search, code_interpreter, computer_use, mcp) whose pricing dimension is not yet wired into the gateway hold estimator.
INVALID_AUDIO_FORMAT: input_audio.format value is not in the supported set. The envelope lists every supported codec name. The gateway accepts both short names (wav, webm) and full MIME aliases (audio/wav, audio/webm); anything else fails fast at admission. See API guide §8b.
AUDIO_NOT_SUPPORTED_ON_RESPONSES: input_audio content part sent to POST /v1/responses. The Responses API has no audio content type today; resend to POST /v1/chat/completions instead.

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

402

Insufficient credit balance.

409

Idempotency key conflict: you sent the same Idempotency-Key with a different request body.

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

451

The submitted image was flagged by our content policy. Explicit or NSFW content is not permitted on image-only models. The prediction does not run. See the Content Policy section above for details on what is screened.

{
  "error": {
    "code": "CONTENT_POLICY_VIOLATION",
    "message": "The submitted image was flagged by our content policy. Explicit or NSFW content is not permitted.",
    "status": 451
  }
}

499

Your HTTP client cancelled the request before the gateway finished. No charge: the hold has been released. The most common cause is a 30 s default client timeout against a model whose p95 latency is 45-60 s; bump your client timeout to 120 s.

Retries with the same Idempotency-Key will replay this 499 forever (the prior outcome is "you cancelled"). For an actual re-attempt, mint a fresh Idempotency-Key. See docs/CUSTOMER_ERROR_HANDLING.md §3 for the full contract.

{
  "error": {
    "code": "CLIENT_CLOSED",
    "message": "Client disconnected before response",
    "status": 499
  }
}

500

Unexpected server error. Please retry with exponential backoff. If the issue persists, contact your admin.

502

The upstream AI provider is temporarily unavailable. Retry with exponential backoff (1s, 2s, 4s) using the same Idempotency-Key: if the upstream actually completed the work and only the response failed, the gateway replays the cached success without a second charge. Holds are released automatically on upstream failures.

503

504

The gateway's 120 s upstream deadline elapsed before the upstream provider produced a response. Retry with the same Idempotency-Key so a delayed-but-eventually-successful upstream call can be replayed instead of re-charged. Consider switching to a faster model or capping max_tokens if this recurs.

{
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "Upstream did not respond before timeout",
    "status": 504
  }
}

POST/v1/models/{owner}/{name}/predictionsاحراز هویت Bearer

Create a prediction (path-based model)

Alternative to POST /v1/predictions where the model is specified in the URL path instead of the request body. Useful for integrations that prefer path-based routing.

Equivalent to calling POST /v1/predictions with "version": "{owner}/{name}".

پارامترها

فیلد	in	نوع	توضیح
`owner`الزامی	path	string	Model owner (e.g., `black-forest-labs`).
`name`الزامی	path	string	Model name (e.g., `flux-pro`).
`Idempotency-Key`	header	string	Optional deduplication token (any string up to 200 characters). How it works: Same key + same request body → cached response replayed (safe retry) Same key + different body → `409 CONFLICT` error Keys expire after 24 hours When to use: Add this header when you want to safely retry a request after a network timeout without risking a duplicate operation.

بدنه درخواستالزامی

فیلد	نوع	توضیح
`input`الزامی	object	Model-specific input parameters.
`webhook`	string (uri)	Optional webhook URL.
`webhook_events_filter`	array of string	Webhook event filter.

نمونه

curlPythonJavaScriptGo

curl https://api.hormouz.net/v1/models/black-forest-labs/flux-schnell/predictions \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "a sunset over mountains"}}'

import requests

resp = requests.post(
    "https://api.hormouz.net/v1/models/black-forest-labs/flux-schnell/predictions",
    headers={"Authorization": "Bearer ng-YOUR_API_KEY"},
    json={"input": {"prompt": "a sunset over mountains"}},
)
print(resp.json()["id"])  # poll GET /v1/predictions/{id} next

const resp = await fetch(
  "https://api.hormouz.net/v1/models/black-forest-labs/flux-schnell/predictions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer ng-YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ input: { prompt: "a sunset over mountains" } }),
  },
);
const pred = await resp.json();
console.log(pred.id); // poll GET /v1/predictions/{id} next

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"input": map[string]string{"prompt": "a sunset over mountains"},
	})
	url := "https://api.hormouz.net/v1/models/black-forest-labs/flux-schnell/predictions"
	req, _ := http.NewRequest("POST", url, bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		ID string `json:"id"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.ID) // poll GET /v1/predictions/{id} next
}

پاسخ‌ها

201

Prediction created.

400

The request body or query parameters are invalid. Check the error.code and error.message fields for details. Codes the gateway emits at 400:

BAD_REQUEST: generic malformed JSON / missing required field.
INVALID_TOOLS: the tools array, plugins field, or model's :online suffix uses an unsupported shape. The response names the offender and links to the supported form. See the dedicated InvalidTools response below for the three triggers and migration hints.
UNSUPPORTED_TOOL: a built-in tool (file_search, code_interpreter, computer_use, mcp) whose pricing dimension is not yet wired into the gateway hold estimator.
INVALID_AUDIO_FORMAT: input_audio.format value is not in the supported set. The envelope lists every supported codec name. The gateway accepts both short names (wav, webm) and full MIME aliases (audio/wav, audio/webm); anything else fails fast at admission. See API guide §8b.
AUDIO_NOT_SUPPORTED_ON_RESPONSES: input_audio content part sent to POST /v1/responses. The Responses API has no audio content type today; resend to POST /v1/chat/completions instead.

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

402

Insufficient credit balance.

409

Idempotency key conflict: you sent the same Idempotency-Key with a different request body.

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

451

Image flagged by content policy. See Content Policy section.

499

{
  "error": {
    "code": "CLIENT_CLOSED",
    "message": "Client disconnected before response",
    "status": 499
  }
}

500

Unexpected server error. Please retry with exponential backoff. If the issue persists, contact your admin.

502

503

504

{
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "Upstream did not respond before timeout",
    "status": 504
  }
}

GET/v1/predictions/{id}احراز هویت Bearer

Get prediction status

Returns the current state of a prediction. Poll this endpoint until status is succeeded (or failed / canceled).

Important: After succeeded, wait for the assets array to be populated before downloading. The background mirror worker typically takes 5–30 seconds to copy outputs to local storage.

Recommended poll interval: Every 2 seconds. Don't poll faster than once per second.

پارامترها

فیلد	in	نوع	توضیح
`id`الزامی	path	string	Prediction ID from the create response.

نمونه

curlPythonJavaScriptGo

curl https://api.hormouz.net/v1/predictions/PREDICTION_ID \
  -H "Authorization: Bearer ng-YOUR_API_KEY"

import requests

pred = requests.get(
    "https://api.hormouz.net/v1/predictions/PREDICTION_ID",
    headers={"Authorization": "Bearer ng-YOUR_API_KEY"},
).json()
print(pred["status"], pred.get("assets"))

const pred = await (await fetch(
  "https://api.hormouz.net/v1/predictions/PREDICTION_ID",
  { headers: { Authorization: "Bearer ng-YOUR_API_KEY" } },
)).json();
console.log(pred.status, pred.assets);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hormouz.net/v1/predictions/PREDICTION_ID", nil)
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	fmt.Println(string(raw))
}

پاسخ‌ها

200

Current prediction state.

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

404

Prediction not found. Either the ID is wrong or it belongs to a different account.

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

503

POST/v1/predictions/{id}/cancelاحراز هویت Bearer

Cancel a prediction

Cancels a running or queued prediction. The prediction status changes to canceled and any held credits are released.

پارامترها

فیلد	in	نوع	توضیح
`id`الزامی	path	string	Prediction ID to cancel.
`Idempotency-Key`	header	string	Optional deduplication token (any string up to 200 characters). How it works: Same key + same request body → cached response replayed (safe retry) Same key + different body → `409 CONFLICT` error Keys expire after 24 hours When to use: Add this header when you want to safely retry a request after a network timeout without risking a duplicate operation.

نمونه

curlPythonJavaScriptGo

curl -X POST https://api.hormouz.net/v1/predictions/PREDICTION_ID/cancel \
  -H "Authorization: Bearer ng-YOUR_API_KEY"

import requests

pred = requests.post(
    "https://api.hormouz.net/v1/predictions/PREDICTION_ID/cancel",
    headers={"Authorization": "Bearer ng-YOUR_API_KEY"},
).json()
print(pred["status"])  # "canceled"

const pred = await (await fetch(
  "https://api.hormouz.net/v1/predictions/PREDICTION_ID/cancel",
  { method: "POST", headers: { Authorization: "Bearer ng-YOUR_API_KEY" } },
)).json();
console.log(pred.status); // "canceled"

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.hormouz.net/v1/predictions/PREDICTION_ID/cancel"
	req, _ := http.NewRequest("POST", url, nil)
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	fmt.Println(string(raw))
}

پاسخ‌ها

200

Cancellation accepted.

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

404

The requested resource was not found. Either the ID is wrong or it belongs to a different account.

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

503

GET/v1/predictions/{id}/streamاحراز هویت Bearer

Stream prediction events (SSE)

Opens a Server-Sent Events stream for real-time prediction updates. Events include output progress, logs, and completion status.

Event types:

output: Partial or final model output
logs: Model execution logs
done: Prediction complete

پارامترها

فیلد	in	نوع	توضیح
`id`الزامی	path	string	Prediction ID.

نمونه

curlPythonJavaScriptGo

curl -N https://api.hormouz.net/v1/predictions/PREDICTION_ID/stream \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  -H "Accept: text/event-stream"

import requests

with requests.get(
    "https://api.hormouz.net/v1/predictions/PREDICTION_ID/stream",
    headers={"Authorization": "Bearer ng-YOUR_API_KEY", "Accept": "text/event-stream"},
    stream=True,
) as resp:
    for line in resp.iter_lines(decode_unicode=True):
        if line:
            print(line)

const resp = await fetch(
  "https://api.hormouz.net/v1/predictions/PREDICTION_ID/stream",
  {
    headers: {
      Authorization: "Bearer ng-YOUR_API_KEY",
      Accept: "text/event-stream",
    },
  },
);
const reader = resp.body.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(value);
}

package main

import (
	"bufio"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.hormouz.net/v1/predictions/PREDICTION_ID/stream"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")
	req.Header.Set("Accept", "text/event-stream")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	scanner := bufio.NewScanner(resp.Body)
	for scanner.Scan() {
		fmt.Println(scanner.Text())
	}
}

پاسخ‌ها

200

Event stream.

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

404

The requested resource was not found. Either the ID is wrong or it belongs to a different account.

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

503

سوالات متداول

چرا باید منتظر پر شدن assets بمانم و نه فقط succeeded؟: آینه‌سازی خروجی چند ثانیه بعد از اتمام کار انجام می‌شود (معمولاً ۵ تا ۳۰ ثانیه). لینک‌های assets روی دامنهٔ هرمز هستند و ۷ روز معتبر می‌مانند؛ لینک منبع خیلی زود منقضی می‌شود.
هزینهٔ prediction چطور محاسبه می‌شود؟: هر مدل قیمت ثابتِ هر اجرا دارد که در کاتالوگ مدل‌ها نمایش داده می‌شود. مبلغ قبل از اجرا از اعتبار بلوکه و پس از پایان تسویه می‌شود؛ اگر کار لغو یا خطا شود، مبلغ آزاد می‌گردد.