Files & assets

Two ways to download model outputs: GET /v1/assets/{id} serves the copy mirrored on Hormouz's servers (recommended. 7-day retention, fast from inside Iran), and GET /v1/files/proxy?url=... is the fallback that relays the source file through Hormouz. Only URLs that the API itself returned in a prediction's output are accepted.

GET/v1/files/proxyBearer auth

Proxy-fetch a generated file

Streams a generated file through this gateway. Use it when:

The source CDN URLs are blocked or slow on your network
The asset mirror hasn't caught up yet (fallback after 90 seconds)
You need a one-shot download without waiting for mirroring

Security: Only file URLs returned by this API (in a prediction's output or urls) are accepted.

Parameters

Field	in	Type	Description
`url`required	query	string (uri)	HTTPS URL of a generated file, as returned in a prediction's `output` or `urls`.

Example

curlPythonJavaScriptGo

curl -G https://api.hormouz.net/v1/files/proxy \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  --data-urlencode "url=FILE_URL_FROM_PREDICTION_OUTPUT" \
  --output output.webp

import requests

resp = requests.get(
    "https://api.hormouz.net/v1/files/proxy",
    headers={"Authorization": "Bearer ng-YOUR_API_KEY"},
    params={"url": "FILE_URL_FROM_PREDICTION_OUTPUT"},
)
open("output.webp", "wb").write(resp.content)

const url = new URL("https://api.hormouz.net/v1/files/proxy");
url.searchParams.set("url", "FILE_URL_FROM_PREDICTION_OUTPUT");

const resp = await fetch(url, {
  headers: { Authorization: "Bearer ng-YOUR_API_KEY" },
});
const bytes = Buffer.from(await resp.arrayBuffer());

package main

import (
	"io"
	"net/http"
	"net/url"
	"os"
)

func main() {
	u, _ := url.Parse("https://api.hormouz.net/v1/files/proxy")
	q := u.Query()
	q.Set("url", "FILE_URL_FROM_PREDICTION_OUTPUT")
	u.RawQuery = q.Encode()

	req, _ := http.NewRequest("GET", u.String(), 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()

	f, _ := os.Create("output.webp")
	defer f.Close()
	io.Copy(f, resp.Body)
}

Responses

200

File content streamed to the client.

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

403

URL is not an accepted generated-file URL.

503

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.

GET/v1/assets/{id}Bearer auth

Download a mirrored asset

Download a file that our background worker copied to local storage. These URLs appear in the assets[] array of completed predictions.

Advantages over the direct source URLs:

Served from the same domain: no CDN blocking issues
Available for 7 days (vs the source's 1-hour expiry)
Faster download from within Iran

Assets are tenant-scoped: you can only download your own.

Parameters

Field	in	Type	Description
`id`required	path	string (uuid)	Asset ID from the prediction's `assets[]` array.

Example

curlPythonJavaScriptGo

curl https://api.hormouz.net/v1/assets/ASSET_ID \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  --output output.webp

import requests

resp = requests.get(
    "https://api.hormouz.net/v1/assets/ASSET_ID",
    headers={"Authorization": "Bearer ng-YOUR_API_KEY"},
)
open("output.webp", "wb").write(resp.content)

const resp = await fetch("https://api.hormouz.net/v1/assets/ASSET_ID", {
  headers: { Authorization: "Bearer ng-YOUR_API_KEY" },
});
const bytes = Buffer.from(await resp.arrayBuffer());

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.hormouz.net/v1/assets/ASSET_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()

	f, _ := os.Create("output.webp")
	defer f.Close()
	io.Copy(f, resp.Body)
}

Responses

200

Asset file content.

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

403

This asset belongs to another account.

404

Asset not found. It may have expired (7-day retention) or the mirror worker hasn't processed it yet.