Why wait for assets, not just status succeeded?

Output mirroring completes a few seconds after the job (typically 5–30s). The assets URLs live on Hormouz's domain and stay valid for 7 days; the source URL expires quickly.

How are predictions billed?

Each model has a fixed per-run price shown in the catalogue. The amount is held from your credit before the run and settled when it finishes; canceled or failed runs release the hold.

Predictions. image, video & audio

Image, video, and audio generation models run asynchronously: create the job with POST /v1/predictions, poll GET /v1/predictions/{id} every ~2 seconds, and download from the assets array once status is succeeded and assets is non-empty. Outputs are mirrored onto Hormouz's own servers for fast, reliable downloads from inside Iran.

POST/v1/predictionsBearer auth

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

Parameters

Field	in	Type	Description
`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.

Request bodyrequired

Field	Type	Description
`version`required	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`. Example: `black-forest-labs/flux-pro`
`input`required	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`.

Example

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)
}

Responses

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}/predictionsBearer auth

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}".

Parameters

Field	in	Type	Description
`owner`required	path	string	Model owner (e.g., `black-forest-labs`).
`name`required	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.

Request bodyrequired

Field	Type	Description
`input`required	object	Model-specific input parameters.
`webhook`	string (uri)	Optional webhook URL.
`webhook_events_filter`	array of string	Webhook event filter.

Example

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
}

Responses

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 auth

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.

Parameters

Field	in	Type	Description
`id`required	path	string	Prediction ID from the create response.

Example

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))
}

Responses

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}/cancelBearer auth

Cancel a prediction

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

Parameters

Field	in	Type	Description
`id`required	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.

Example

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))
}

Responses

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}/streamBearer auth

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

Parameters

Field	in	Type	Description
`id`required	path	string	Prediction ID.

Example

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())
	}
}

Responses

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

FAQ

Why wait for assets, not just status succeeded?: Output mirroring completes a few seconds after the job (typically 5–30s). The assets URLs live on Hormouz's domain and stay valid for 7 days; the source URL expires quickly.
How are predictions billed?: Each model has a fixed per-run price shown in the catalogue. The amount is held from your credit before the run and settled when it finishes; canceled or failed runs release the hold.