Highsfield / FOR DEVELOPERS

Your next workflow starts here.

Bring Highsfield into your app or automation with a simple REST API. One account, the same credits, and the same generation engine.

Create an API key Read the quickstart ↓

API base URLhttps://highsfield.com/api/v1

01 / GET CONNECTED

Start with your account key.

Create a key in Settings → API Keys, then set MEDIA_API_KEY in your local environment. Keys belong to this site and use your account credits. Keep them on your server or in a trusted local client; never put them in public frontend code.

Discover this site’s models

curl 'https://highsfield.com/api/v1/models' \
  -H "Authorization: Bearer $MEDIA_API_KEY"

02 / QUOTE, CREATE, RETRIEVE

Know the cost before you create.

Model availability and prices come from this site’s live catalog. Choose a supported parameter combination; example dimensions and durations below are illustrative. Some models require a previous successful account payment.

1. Request a quote

POST /api/v1/images · no charge

curl 'https://highsfield.com/api/v1/images' \
  -H "Authorization: Bearer $MEDIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "dry_run": true,
  "model": "MODEL_ID_FROM_CATALOG",
  "mode": "generate",
  "prompt": "Soft morning light over a quiet mountain lake",
  "aspectRatio": "1:1"
}'

The response contains data.credits, data.pricingRevision and data.maxCredits. A quote does not reserve funds or guarantee that a later request passes moderation.

2. Confirm the price and submit

Send the same settings to the same endpoint. Replace all placeholders below, including maxCredits, with the quote you approved. Keep this exact body for retries.

POST /api/v1/images · request body

{
  "dry_run": false,
  "model": "MODEL_ID_FROM_CATALOG",
  "mode": "generate",
  "prompt": "Soft morning light over a quiet mountain lake",
  "aspectRatio": "1:1",
  "requestId": "REPLACE_WITH_A_NEW_UUID",
  "pricingRevision": "COPY_FROM_QUOTE",
  "maxCredits": 100
}

3. Poll for the result

Read data.tasks[0].id from the receipt. On success, data.files contains result URLs.

GET /api/v1/tasks/:taskId

curl 'https://highsfield.com/api/v1/tasks/TASK_ID_FROM_RECEIPT' \
  -H "Authorization: Bearer $MEDIA_API_KEY"

03 / REFERENCE

A small API for the whole workflow.

Endpoint	What it does
`GET /api/v1/models`	Available models, public IDs and supported parameter quotes.
`GET /api/v1/credits`	Current account credit balance.
`POST /api/v1/images`	Quote or create one image; text generation or a reference image edit.
`POST /api/v1/videos`	Quote or create one video; text generation or image-to-video.
`GET /api/v1/tasks/:taskId`	Your task status, charged credits and result URLs.
`POST /api/v1/uploads`	Upload an owned reference image (multipart field: file).

Response format

REST response envelope

{ "code": 0, "message": "ok", "data": { ... } }
{ "code": -1, "message": "Error description" }

HTTP 200: read or quote. HTTP 202: task receipt. HTTP 400: invalid parameters. HTTP 401: invalid key. HTTP 403: access denied. HTTP 404: task not found. HTTP 409: stale quote or conflicting request. HTTP 413: body too large. HTTP 429: rate limited. HTTP 503: temporarily unavailable or receipt uncertain.

04 / USAGE & LIMITS

Built on your existing account.

Credits, retries and refunds

Generation uses the same account balance and settlement rules as the website. Each request creates one output. Reuse the identical UUID and body after a timeout; a new UUID creates a new paid task. If pricing changes, review a new quote before submitting a new request. Check task status and account credit history for failure settlements.

Reference images and supported workflows

Upload a reference to this site first. Use data.urls[0] as referenceImageUrl with mode: "edit". Only references owned by your account are accepted. Maximum image size: 10 MiB, 40 megapixels. Website-specific motion-transfer and studio recipes are not part of this API.

Upload a reference image

curl 'https://highsfield.com/api/v1/uploads' \
  -H "Authorization: Bearer $MEDIA_API_KEY" \
  -F 'file=@reference.png'

Request limits and key security

JSON requests are limited to 32 KiB. Poll at intervals of at least 3 seconds. Generation also follows this site’s queue and account limits. For HTTP 429, respect Retry-After; for MCP rate-limit tool errors, wait one minute. Revoke unused keys in Settings. Keys from another site cannot access this account.

Need help? support@highsfield.com · Connect an MCP client →