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.
- Scope
postory:drafts - Limit class
MEDIA - Success
200
Request body
| Field | Type | Description |
|---|---|---|
confirmation_tokenrequired | string | The quote's single-use token, after the user's yes. Up to 128 characters |
Example
curl https://postory.io/api/v1/images \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"confirmation_token": "<confirmation_token>"}'{
"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
401No API key, or an invalid or revoked one
402Not enough credits for this delivery; see
buy_url403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate limit spent; see Retry-After
GET /api/v1/images/{generation_id}
One AI image's result: status, credits_charged, destination and, on success, image.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
generation_idrequired | path | string | Up to 36 characters |
wait_s | query | integer | Seconds to wait while it is pending, 0-20 (default 15). From 0 to 20 |
Example
curl "https://postory.io/api/v1/images/<generation_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"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
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
422A request parameter is not valid
429Rate 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.
- Scope
postory:drafts - Limit class
MEDIA - Success
200
Request body
| Field | Type | Description |
|---|---|---|
aspect_ratio | "1:1" | "4:5" | "16:9" | Default 1:1. |
folder | string | A media library folder (id or name), without |
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); |
part | integer | The draft's 1-based thread part, with |
post_id | string | Put the image on this draft ( |
promptrequired | string | What the image shows. Up to 2000 characters |
resolution | "1K" | "2K" | "4K" | Default the model's own; not every model draws every tier. |
Example
curl https://postory.io/api/v1/images/quote \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "<prompt>"}'{
"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
401No API key, or an invalid or revoked one
402Not enough credits for this delivery; see
buy_url403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate limit spent; see Retry-After