API guide

Quick start

Register and verify your email, sign in, create an API key, then select a model. No credit is required during unmetered testing. Choose an available model before sending a request.

Base URL https://modelhub.frankcfbackup.uk/v1

Compatibility: GET /v1/models uses the OpenAI list format. Image and video generation use ModelHub asynchronous jobs (202 plus polling), not drop-in OpenAI SDK responses. Claude Messages (/v1/messages), Responses, image edits and reference inputs are not supported. Chat Completions exists, but no text models are currently published.

curl "https://modelhub.frankcfbackup.uk/v1/images/generations" \
  -H "Authorization: Bearer $MODELHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "gpt-image-2",
  "prompt": "A small ceramic vase on a warm gray background."
}'

Authentication

Send your ModelHub API key in the Authorization header. You never need a supplier key. Keep your key on your application server. Revoked keys stop working immediately.

Authorization: Bearer mh_YOUR_API_KEY

Each new generation needs an Idempotency-Key (1–100 characters). Save it before sending. To retry the same operation, reuse the same key and body.

Models & pricing

GET /v1/models returns only published models. The catalog also shows planned profiles and their availability. Prices are USD per successful generation at the displayed fixed specification, not per token.

curl "https://modelhub.frankcfbackup.uk/v1/models" -H "Authorization: Bearer $MODELHUB_API_KEY"

View models and fixed parameters →

Image generation

Text-to-image, one image per request. The API returns HTTP 202 and a ModelHub job ID immediately. Poll GET /v1/images/{id} for the result. This is an asynchronous ModelHub contract; it is not a drop-in synchronous OpenAI images response.

curl "https://modelhub.frankcfbackup.uk/v1/images/generations" \
  -H "Authorization: Bearer $MODELHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "gpt-image-2",
  "prompt": "A small ceramic vase on a warm gray background."
}'

Required: model and prompt (1–8,000 characters). Optional profile parameters must exactly match the model catalog. Arbitrary sizes, multiple images, image editing, callbacks, extra_body and reference assets are not supported in this version.

Video generation

Text-to-video. Return HTTP 202, then poll GET /v1/videos/{id}. Duration, resolution, aspect ratio and audio settings are fixed per model. You do not need to send async.

curl "https://modelhub.frankcfbackup.uk/v1/videos/generations" \
  -H "Authorization: Bearer $MODELHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "SIRAYA-Seedance-2.0-fast",
  "prompt": "A slow camera movement through a sunlit forest."
}'

Reference images, audio/video inputs, frame control and video editing are not available in this release.

Job status & results

{
  "id": "mh_image_JOB_ID",
  "object": "image",
  "model": "gpt-image-2",
  "status": "queued",
  "created_at": 1788696000,
  "charge": 0,
  "reserved": 50000,
  "billing_status": "processing",
  "result_expires_at": 0
}

Illustrative amounts only; this response is not a price quote. Monetary response fields use micro-USD: 1 USD = 1,000,000 units.

curl "https://modelhub.frankcfbackup.uk/v1/images/mh_image_JOB_ID" \
  -H "Authorization: Bearer $MODELHUB_API_KEY"

Completed images contain result.data[0].b64_json or url. Videos contain result.data[0].url. Save the result promptly: response data is retained for 24 hours; external download links may expire earlier. Only the job owner can query it.

Billing & retries

In unmetered mode, charge and reserved are both zero; no customer credit is deducted. In metered mode, credit is reserved before submitting and charged once on successful completion at the saved quote. A confirmed failure releases the hold. An interrupted or uncertain submission keeps the hold for review. Never create a new generation just because a request timed out.

Retry submission with the same Idempotency-Key and identical body; query existing jobs instead of recreating them. Poll every 5–10 seconds and back off on 429. Limits: 12 submissions/minute, 120 queries/minute per account, and at most 4 active requests.

Errors

{
  "error": {
    "code": "model_not_published",
    "message": "This model is not published."
  }
}