Ask Pixel to change a customer's design
const url = 'https://api.pixonaut.app/v1/pixel/designer';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"prompt":"Put my name, Alva, on it in a playful font","templateId":"tshirt-basic@2","values":{"headline":{"content":"Class of 2026"}}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.pixonaut.app/v1/pixel/designer \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Put my name, Alva, on it in a playful font", "templateId": "tshirt-basic@2", "values": { "headline": { "content": "Class of 2026" } } }'Operation ID: pixel.designer
Pixel, for the customer in the designer: from their prompt and their values as they stand, Pixel changes what the template offers them, within what each field allows, and may generate a picture for an offered picture or cut the customer’s picture out of its background, as the template’s settings allow. It never changes what the template keeps fixed. The answer is the values with Pixel’s changes, for the designer to apply. Paid from the workspace’s credits, within the template’s limits for one designer session (x-pixonaut-session, required) and the workspace’s monthly ceiling. Whatever stops it — the template or the workspace has it off, a limit or the ceiling is reached, or the credits run out — it answers 503 pixel_unavailable and nothing else, for the designer to say it did not work.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”The designer’s browser session, which the SDK sends so one visitor’s uploads and proofs are told apart from another’s on the same key: 6 to 64 letters, digits, _ or -. Any other value is ignored.
The designer’s browser session, which the SDK sends so one visitor’s uploads and proofs are told apart from another’s on the same key: 6 to 64 letters, digits, _ or -. Any other value is ignored.
Request Bodyrequired
Section titled “Request Bodyrequired”object
What the customer asks Pixel, in their own words.
The template version the designer shows, baseId@version.
The customer’s values as the designer holds them, by layer id and then prop, as a proof sends them.
object
object
Examples
Example
{ "prompt": "Put my name, Alva, on it in a playful font", "templateId": "tshirt-basic@2", "values": { "headline": { "content": "Class of 2026" } }}Responses
Section titled “Responses”The customer’s values with Pixel’s changes
object
Each field Pixel changed, in the order it first changed.
object
Each picture Pixel is cutting out of its background: read GET /v1/assets/{id}/cut-out with its assetId until it is done, then put the cut-out in its place.
object
Each layer of the customer’s own Pixel added or removed, in the order it did, by the id it had then. values holds the layers that remain: the kinds under $added, each layer’s values under its id.
object
What Pixel says it did, for the customer, in their language.
The customer’s values with Pixel’s changes applied: what the designer shows next.
object
object
Examples
Example
{ "changed": [ { "layerId": "name", "prop": "content" }, { "layerId": "name", "prop": "fontFamily" } ], "cutOuts": [], "layers": [], "reply": "I wrote Alva as the name and set it in Poppins.", "values": { "headline": { "content": "Class of 2026" }, "name": { "content": "Alva", "fontFamily": "Poppins" } }}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: no_session, invalid_input
object
Always sent with invalid_input.
Examples
invalid_input
{ "error": "invalid_input", "reason": "string"}no_session
{ "error": "no_session"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: unauthorized
object
Examples
unauthorized
{ "error": "unauthorized"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: origin_forbidden, forbidden, feature_disabled
object
The feature the tenant does not have. Always sent with feature_disabled.
Examples
feature_disabled
{ "error": "feature_disabled", "feature": "api"}forbidden
{ "error": "forbidden"}origin_forbidden
{ "error": "origin_forbidden"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: not_found
object
Examples
not_found
{ "error": "not_found"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: payload_too_large
object
Always sent with payload_too_large.
Examples
payload_too_large
{ "error": "payload_too_large", "maxBytes": 0}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: rate_limited
object
Examples
rate_limited
{ "error": "rate_limited"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: db_error. A request that failed unexpectedly answers as text instead.
object
Examples
db_error
{ "error": "db_error"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: lock_timeout, pixel_unavailable
object
Examples
lock_timeout
{ "error": "lock_timeout"}pixel_unavailable
{ "error": "pixel_unavailable"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Questions? Write to [email protected].