Docs menuImages

Images

POST /api/v1/images

Start the quoted image with its confirmation_token; waits up to ~20 s. pending: follow it with GET /images/{generation_id}. Charged only for an image that was stored, never more than the quote.

  • Scopepostory:drafts
  • Limit classMEDIA
  • Success200

Request body

FieldTypeDescription
confirmation_tokenrequiredstring

The quote's single-use token, after the user's yes.

Up to 128 characters

Example

Request
curl https://postory.io/api/v1/images \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token": "<confirmation_token>"}'
Response 200
{
  "balance_credits": 0,
  "confirmation_token": "<confirmation_token>",
  "credits_charged": 0,
  "error_code": "<error_code>",
  "generation_id": "<generation_id>",
  "price_credits": 0,
  "status": "<status>"
}

Other responses

401

No API key, or an invalid or revoked one

402

Not enough credits for this delivery; see buy_url

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

GET /api/v1/images/{generation_id}

One AI image's result: status, credits_charged, destination and, on success, image.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
generation_idrequiredpathstringUp to 36 characters
wait_squeryinteger

Seconds to wait while it is pending, 0-20 (default 15).

From 0 to 20

Example

Request
curl "https://postory.io/api/v1/images/<generation_id>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "balance_credits": 0,
  "confirmation_token": "<confirmation_token>",
  "credits_charged": 0,
  "error_code": "<error_code>",
  "generation_id": "<generation_id>",
  "price_credits": 0,
  "status": "<status>"
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

POST /api/v1/images/quote

Price an AI image and check it can start; the answer's single-use confirmation_token is for POST /images after the user's yes. Nothing is made or charged. credit_limit (402) carries buy_url.

  • Scopepostory:drafts
  • Limit classMEDIA
  • Success200

Request body

FieldTypeDescription
aspect_ratio"1:1" | "4:5" | "16:9"

Default 1:1.

folderstring

A media library folder (id or name), without post_id. Omitted: no folder.

Up to 100 characters
model"google/gemini-nano-banana-2.1" | "openai/gpt-5.4-image-2" | "x-ai/grok-imagine-image-2.0" | "bytedance-seed/seedream-5-5"

The image model (default Nano Banana); models in the quote lists each with its prices.

partinteger

The draft's 1-based thread part, with post_id.

From 1 to 25
post_idstring

Put the image on this draft (part, default 1). Omitted: the media library.

Up to 36 characters
promptrequiredstring

What the image shows.

Up to 2000 characters
resolution"1K" | "2K" | "4K"

Default the model's own; not every model draws every tier.

Example

Request
curl https://postory.io/api/v1/images/quote \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "<prompt>"}'
Response 200
{
  "balance_credits": 0,
  "confirmation_token": "<confirmation_token>",
  "credits_charged": 0,
  "error_code": "<error_code>",
  "generation_id": "<generation_id>",
  "price_credits": 0,
  "status": "<status>"
}

Other responses

401

No API key, or an invalid or revoked one

402

Not enough credits for this delivery; see buy_url

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After