Regenerate an AI design

POST

/v1/accounts/{accountId}/posts/{postId}/design/regenerate

curl --request POST \
  --url https://api-v1.tailwind.ai/v1/accounts/example/posts/example/design/regenerate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "title": "example", "premiumStyle": "image-highlight", "userFeedback": "example", "selectedVariationUrl": "example", "mediaUrl": "example", "uploadId": "example" }'

• Production
• Development

Have Tailwind’s AI generate a new design for a premium (AI-designed) Pin. Asynchronous and metered: it spends plan credits, takes a few minutes, and returns a job id to poll with GET /v1/design-regenerations/{jobId}. Only valid when supportedOperations includes regenerate. The result does NOT replace the Pin’s design: a finished regeneration returns a variationUrl that must be applied through the variation endpoint. To revise the design the Pin already has rather than replace it, pass selectedVariationUrl - the generator only enters its edit path when that URL matches an existing premium variation, so omitting it spends the same credits on an unrelated design. Billing is charged to the account in the path, never to another account in the organization. An Idempotency-Key header is required so a retried request returns the original job instead of charging again.

Authorizations

• bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

postId

required

string

Post ID

Header Parameters

Idempotency-Key

required

string

<= 191 characters

Caller-generated key. The same key with the same post and body replays the original job; the same key with a different post or body is a 409.

Request Body

Media typeapplication/json

object

title

string

<= 256 characters

premiumStyle

string

Allowed values: image-highlight text-highlight minimalist artistic professional natural

userFeedback

What to change, in the user’s own words

string

<= 2000 characters

selectedVariationUrl

The variation to revise. Must be one of this draft’s AI-generated variations; a URL it does not carry is rejected before anything is charged. Omit to generate a fresh, unrelated design.

string

<= 2048 characters

mediaUrl

Use instead of uploadId, not with it

string

<= 2048 characters

uploadId

string

<= 191 characters

Responses

202

Regeneration accepted and processing

Media typeapplication/json

object

data

object

regeneration

object

id

required

string

status

required

string

Allowed values: processing

creditCost

number

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "regeneration": {
      "status": "processing"
    }
  }
}

400

Invalid request

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string

resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body"
  },
  "meta": {
    "requestId": "abc123"
  }
}

401

Authentication required or invalid bearer credentials

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string

resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "abc123"
  }
}

402

The path account cannot be billed for this regeneration

404

Resource not found

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string

resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account not found"
  },
  "meta": {
    "requestId": "abc123"
  }
}

409

The draft’s tier does not support regeneration, or the Idempotency-Key was already used for a different request

422

The supplied image could not be processed

429

Rate limit exceeded

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string

resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit of 10000 requests for this organization exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}

Headers

Retry-After

integer

Seconds until the daily limit resets at midnight UTC.