POST /v1/summaries

Create a summary — Shorty API

Starts an async summary job for a YouTube video, a web page, or pasted text, selected by the `source` field. Usually responds 202 with a `Location` header and a `job_id` you can poll at GET /v1/jobs/{id} (send an `Idempotency-Key` header to make retries safe). If the exact source was already summarized in the requested language it responds 200 `already_complete` with the `article_id` and no job to poll.

Open in Claude Open in ChatGPT

POST /v1/summaries

Starts an async summary job for a YouTube video, a web page, or pasted text, selected by the source field. Usually responds 202 with a Location header and a job_id you can poll at GET /v1/jobs/{id} (send an Idempotency-Key header to make retries safe). If the exact source was already summarized in the requested language it responds 200 already_complete with the article_id and no job to poll.

Authentication

Requires a Bearer credential — a shk_live_ API key or an OAuth 2.1 access token with the scope for this resource. See Authentication.

Parameters

Name	In	Required	Description
`Idempotency-Key`	header	No	Optional client-generated key (1–255 visible ASCII chars) that makes this POST replay-safe: a retry with the SAME key and body returns the original response (with `Idempotency-Replayed: true`) instead of creating a duplicate. Reusing a key with a different body is rejected (422).

Request body

source: "youtube"

Field	Type	Required	Description
`source`	`"youtube"`	Yes	—
`url`	`string<uri>`	Yes	A YouTube video URL.
`language`	`string`	No	Language name ("english") or ISO-639-1 code ("en"). Defaults to english. (2–20 chars) Default: "english".

source: "url"

Field	Type	Required	Description
`source`	`"url"`	Yes	—
`url`	`string<uri>`	Yes	A web page / article URL to summarize.
`language`	`string`	No	Language name ("english") or ISO-639-1 code ("en"). Defaults to english. (2–20 chars) Default: "english".

source: "text"

Field	Type	Required	Description
`source`	`"text"`	Yes	—
`content`	`string`	Yes	The raw text to summarize.
`title`	`string`	No	Optional title hint (reserved — currently derived by the summarizer).
`language`	`string`	No	Language name ("english") or ISO-639-1 code ("en"). Defaults to english. (2–20 chars) Default: "english".

Example request

curl -X POST https://aishorty.com/v1/v1/summaries \
  -H "Authorization: Bearer shk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'

Response · 200

Field	Type	Required	Description
`status`	`"already_complete"`	Yes	Marks a cache hit: this exact source was already summarized, so no new job was started.
`article_id`	`string`	Yes	The id of the already-complete article — fetch it at GET /v1/articles/{id}.

Errors

On failure this endpoint returns an RFC 9457 problem body. Possible statuses:

400
401
403
409
422
429
500
503

Switch on the problem code, not the status. See the error reference for every code and how to fix it.

This endpoint honors an Idempotency-Key header: a retry with the same key and body replays the original response for 24 hours instead of creating a duplicate job.