Endpoint reference

Image generation

POST /v1/images/generate · Synchronous

This route accepts strict JSON. Unknown fields, malformed values, wrong-operation keys, and package settings outside the locked configuration are rejected before provider execution.

Required headers

Header	Value	Notes
`Authorization`	`Bearer $URTHEPRODUCT_API_KEY`	Required. Must be sent from a trusted server.
`Idempotency-Key`	8–128 safe characters	Required on POST. Reuse only for retries of the same logical request.
`Content-Type`	`application/json`	Required on POST.

Request fields

Field	Type	Required	Rules
`prompt`	string	Yes	1–32,000 characters.
`input_upload_id`	upload ID	No	A verified, owned image upload when supported.
`style`	string	No	1–120 characters; must remain within product restrictions.
`output_format`	enum	No	png, jpeg, or webp; locked package settings control acceptance.

Request example

curl "https://urtheproduct.com/v1/images/generate" \
+  -X POST \
+  -H "Authorization: Bearer $URTHEPRODUCT_API_KEY" \
+  -H "Idempotency-Key: logical-request-001" \
+  -H "Content-Type: application/json" \
+  -d '{  "prompt": "Place the authorized product on a neutral studio background.",  "input_upload_id": "upl_example_identifier",  "output_format": "png"}'

{
  "prompt": "Place the authorized product on a neutral studio background.",
  "input_upload_id": "upl_example_identifier",
  "output_format": "png"
}

Success response

{
  "id": "usage-event-id",
  "object": "generation",
  "operation": "images.generate",
  "output": { "url": "short-lived-private-signed-url", "expires_at": "..." },
  "usage": { "charged_units": 1, "remaining_units": 19 }
}

Operation-specific behavior

Create and verify the optional input through the private upload flow.
Output URLs are short-lived and must not be treated as public permanent storage.

Failures and retries

Schema failures return 422 validation_error without charging quota. Wrong scope returns 403 forbidden. Rate/concurrency pressure returns 429 rate_limited. Provider safety pauses return 503 provider_unavailable. Follow the error and retry table and reuse the same idempotency key for the same logical request.