Skip to main content
POST
/
generate
/
images
Generate images
curl --request POST \
  --url https://api.horizon.new/v1/generate/images \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "<string>",
  "count": 1,
  "aspectRatio": "16:9",
  "style": "cinematic",
  "webhookUrl": "<string>"
}'
{
  "jobId": "job_01hx9q9",
  "status": "queued",
  "statusUrl": "<string>",
  "result": {},
  "etaSeconds": 123,
  "jobType": "extract/pdf"
}
Create concept art, UI mockups, or marketing imagery from a natural language prompt. The service renders high-resolution PNGs or WEBPs and stores them in your workspace bucket for later reuse.

​
Request body

  • prompt — Required description of the desired image.
  • count — Optional integer (1–8) for how many variants to produce; defaults to 1.
  • aspectRatio — Optional ratio string such as 1:1, 3:2, or 9:16; defaults to 1:1.
  • style — Optional style preset (cinematic, illustration, photographic, etc.).
  • webhookUrl — Optional HTTPS URL Horizon should call when the image job finishes.

​
Sample request

curl https://api.horizon.new/v1/generate/images \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Futuristic city library filled with holographic shelves",
    "count": 3,
    "aspectRatio": "16:9",
    "style": "cinematic"
  }'

​
Response

Returns 202 Accepted with a jobId and array of placeholder asset records. Poll the provided statusUrl or listen for your webhook to receive the final download locations. Each finished asset includes url, width, height, and checksum details.

​
Notes

  • Use count = 1 when latency matters; batching increases turnaround time slightly.
  • Generated assets respect your workspace retention policy; copy them to long-term storage if needed.
  • GET /jobs/{jobId} (mirrors the statusUrl) lets you check progress or fetch the finished assets later without storing the initial response.

​
x402 flow

Image rendering requests are billed through Coinbase’s x402 protocol. If payment is missing, Horizon issues 402 Payment Required with a structured challenge: 
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "250000",               // $0.25 in 6‑decimal USDC
      "resource": "POST /generate/images",
      "description": "Horizon image generation",
      "mimeType": "application/json",
      "payTo": "0xYourReceivingWallet",
      "maxTimeoutSeconds": 180,
      "asset": "0xYourUSDCContract",
      "extra": {
        "name": "USDC",
        "version": "1"
      }
    }
  ],
  "error": null
}
Follow the Coinbase flow to satisfy the requirement:
  1. Forward the accepts entry to a facilitator (/verify, /settle) as described in the facilitator docs.
  2. Obtain the Base64 Payment Payload and replay the request with an X-PAYMENT header: 
    curl https://api.horizon.new/v1/generate/images \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLC4uLn0=" \
  -d '{ ...original body... }'
  3. Horizon validates the payload (directly or via facilitator) before resuming processing. Successful responses can include X-PAYMENT-RESPONSE with settlement details.
Need infrastructure? The Quickstart for sellers explains how to provision facilitator credentials and wallets.

Body

application/json
​
prompt
string
required
​
count
integer
default:1
Required range: 1 <= x <= 8
​
aspectRatio
string
Example:

"16:9"

​
style
string
Example:

"cinematic"

​
webhookUrl
string<uri>

Webhook to call when the image job completes.

Response

Image generation job accepted

​
jobId
string
required
Example:

"job_01hx9q9"

​
status
enum<string>
required
Available options:
queued,
processing,
completed,
failed
​
statusUrl
string<uri>
required

Canonical link to GET /jobs/{jobId} for this job.

​
jobType
string
required
Example:

"extract/pdf"

​
result
object | null

Present when the job completes synchronously.

​
etaSeconds
integer | null

Estimated seconds until completion.