DEVELOPER & AGENT REFERENCE

Quote. Pay.
Poll the result.

Prompt402 is an asynchronous Higgsfield API proxy with x402 v2 exact payments. Clients pay in USDC using their own wallet. No Prompt402 subscription or client-side Higgsfield credential is required.

OpenAPI 3.1 schema

1. Request a live quote

POST a supported generation body to /api/v1/quote. This endpoint does not settle a payment or submit a generation. The response includes upstreamUsd, priceUsdc, priceMicros, and expiresInSeconds. Quotes are cached for up to 60 seconds; the later payment challenge determines the payable amount.

cURL · quote only
curl 'https://prompt402.com/api/v1/quote' \
  -H 'Content-Type: application/json' \
  -d '{"operation":"bytedance/seedance-2.5/text-to-video","prompt":"A slow pan across a harbor at dawn","duration":5,"resolution":"720p","generate_audio":true}'

Read the 10% markup and rounding policy.

2. Submit with an x402 payment

POST the same body to /api/v1/generations with an Idempotency-Key header of 8–255 characters. An unpaid request receives HTTP 402. An x402-compatible client inspects the requirements, signs with its wallet, and retries with PAYMENT-SIGNATURE. Keep the body and key unchanged across the payment retry.

Production uses Base mainnet (eip155:8453), while development and previews use Base Sepolia (eip155:84532) and test USDC. Read the challenge for the deployment’s active network and amount. The proxy does not custody your signing key.

Successful submission returns HTTP 202 with a generation object and relative poll URL. This means the request was submitted, not that video generation has finished.

3. Poll the returned job

GET the returned poll URL at most once every two seconds. Only job IDs submitted and recorded by this service can be polled; unknown IDs return 404. The response relays upstream status. Follow Retry-After on a 429 response.

Rate limits are 10 quote requests and 10 generation attempts per IP per minute in separate buckets, plus 30 status polls per IP per minute. These limits are process-local.

Accepted models and inputs

Seedance 2.5 text-to-video accepts integer durations of 4–30 seconds, 480p or 720p, six aspect ratios, MP4 or MOV, and optional generated audio. Defaults are 5 seconds, 720p, 16:9, MP4, and audio enabled.

Seedance 2.0 text-to-video remains available at bytedance/seedance-2.0/text-to-video: 5 or 10 seconds; 480p, 720p, or 1080p; 16:9, 9:16, or 1:1; optional audio. Its defaults remain 5 seconds, 720p, 16:9, and audio disabled. Both operations require a nonblank prompt of at most 2,000 characters.

Unknown fields are stripped. The proxy does not support arbitrary model slugs or media inputs. Use the model-specific schemas rather than inferring support from Higgsfield’s catalog.

Retries and failure handling

Replaying a completed submission with the same body and Idempotency-Key returns its original job without charging again. Conflicting or in-progress keys return 409. Validation and rate-limit failures occur before payment.

Payment settles upfront. A 502 after rejected submission is recorded for refund review; a 500 after payment means the submission could not be recorded and needs reconciliation. Refunds are not automatic. Keep your key and response details, and do not start another paid request to resolve an uncertain outcome.

Discovery URLs