> ## Documentation Index > Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt > Use this file to discover all available pages before exploring further. # Publish a post > Publish a post to your public BudgetPixel feed — the same posts you create on the site, so your local agent can publish on your behalf. **Synchronous**: the response carries the live post's `id` and `url`. **Pricing: 10 credits per successful post**, charged only on success. Estimate via [`POST /v1/cost`](/api-reference/models/estimate-the-cost-of-a-request) with `{"model": "create-post"}`. **Media composition** (one of): - **Images** — 1 to 6 images. Each image can optionally carry `model` and `prompt` generation info, shown on the image's info panel on the post. - **Video** — exactly 1 video, optionally with up to 3 accompanying images. - **Audio** — exactly 1 audio file (cannot mix with other media). Supports `song_name`, `genre`, `lyrics`, and dedicated `cover_image` art (the cover is NOT a media item — pass it in its own field). Each `media[].file` accepts a public URL, an uploaded-file URL from [`POST /v1/uploads`](/api-reference/files/upload-input-media), a data URI, or raw base64. **Size limits:** images 15 MB; audio 50 MB; video 100 MB — note that URL inputs are fetched with a 30 MB cap and uploads support up to 50 MB, so ~50 MB is the practical video ceiling via the API. **Limits & moderation:** - The API allows **5 posts per hour**, inside the site-wide limit of **20 posts per hour** per account across all surfaces (shares included) — both on top of the API's global rate limits. Exceeding any of them returns `429`. - Posting a byte-identical file you've already posted returns `409` with the existing post's id. - Posts published through the API carry a public **"via API"** label, like posts made with an Ava companion carry hers. - Image/video posts are **reviewed after publishing** (content rating and spam scoring). Feed and gallery visibility follow that review and your account standing; a post hidden by review is not refunded. **License:** pass `license` to choose the post's content license, exactly like the license picker in the site's post composer: `arr` (All Rights Reserved — the default), `cc-by` (Creative Commons Attribution 4.0) or `cc0` (Creative Commons Zero, public domain). Omit it and the post is published All Rights Reserved. A Creative Commons license is a permanent grant: **the license cannot be changed after publishing**, in either direction — deleting the post is the only way to stop offering it. An unrecognised value is treated as `arr` rather than rejected; the response's `license` always states what the post was published under. **Clan themes:** pass `theme_id` to enter the post in a live clan theme, exactly like choosing a theme in the site's post composer. [`GET /v1/themes`](/api-reference/social/list-themes-you-can-post-to) lists the live themes of the clans you own or have joined. Posting to a live theme of a clan you haven't joined joins you to that clan, as it does on the site. The theme is checked before anything is fetched or charged: an unknown id returns `404 theme_not_found`, a theme that hasn't started or has ended returns `400 theme_not_active`, and a clan you're banned from (or whose owner you have a block with) returns `403 theme_not_permitted`. Theme entries cost the same 10 credits as any post. ## OpenAPI ````yaml /openapi.yaml post /posts openapi: 3.1.0 info: contact: email: support@budgetpixel.com name: BudgetPixel Support description: > The BudgetPixel developer API for programmatic image, video, music and sound-effect generation. Generation is **asynchronous**: you create a job, then poll its status until it reaches a terminal state (`succeeded` / `failed`). You are charged in credits only on success — never for failures, timeouts, or content blocked before generation. **Authentication.** All requests require an API key sent as a bearer token: Authorization: Bearer bpx_live_xxx Create and manage keys from your BudgetPixel account dashboard. The developer API is available on **every paid plan**. On the **Free** plan, API keys can call one endpoint: `GET /v1/stock/images`, the free stock image library search. **Pricing.** API usage is metered in credits at each model's published price (see `GET /v1/models`), and your plan's model discounts and active promotions apply to API charges exactly as they do on the web — `POST /v1/cost` quotes your discounted price. Pro and Ultra plans include a daily free-models allowance (a shared pool of free generations per day across qualified image models such as FLUX 2 Klein and Qwen-Image) that covers API requests too — the standard price applies once the day's pool is used. Other promotional free daily generations remain web/app-only. Failed generations are never charged. **Rate limits.** Requests are limited per minute: **600 requests/min per API key** and **1200 requests/min per source IP** (defaults; subject to tuning). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (seconds until the window resets). Exceeding a limit returns HTTP `429` with a `Retry-After` header — wait that long before retrying. Rejected requests still count against the window, so a tight retry loop keeps you limited; back off instead. Generation jobs additionally have a per-plan concurrency cap (the same one as the web workshop), independent of these request limits. `POST /v1/uploads` also has a dedicated **60 uploads/min per account** cap (it's free/unmetered) on top of these limits. title: BudgetPixel API version: '2026-06-20' servers: - description: Production url: https://api.budgetpixel.com/v1 security: - ApiKeyAuth: [] tags: - description: Account and credit balance name: Account - description: Discover available models and pricing name: Models - description: Upload input media for image/video generation name: Uploads - description: Image job status name: Images - description: FLUX image models name: Black Forest Labs - description: SeeDream image models name: Bytedance - description: Video job status name: Videos - description: Kuaishou Kling video models name: Kling - description: SeeDance video models name: ByteDance (SeeDance) - description: Music and sound-effect job status name: Audios - description: Music generation models name: Music - description: Text-to-sound-effect models (priced per second) name: Sound Effects - description: Format conversion for images, video, and audio name: Conversions - description: Publish posts to your BudgetPixel feed and enter clan themes name: Social - description: Content moderation — NSFW rating and CSAM detection name: Moderation - description: Content classification — music genre detection name: Classification - description: >- Search the free stock image library — available on every plan, including Free name: Stock Images paths: /posts: post: tags: - Social summary: Publish a post description: > Publish a post to your public BudgetPixel feed — the same posts you create on the site, so your local agent can publish on your behalf. **Synchronous**: the response carries the live post's `id` and `url`. **Pricing: 10 credits per successful post**, charged only on success. Estimate via [`POST /v1/cost`](/api-reference/models/estimate-the-cost-of-a-request) with `{"model": "create-post"}`. **Media composition** (one of): - **Images** — 1 to 6 images. Each image can optionally carry `model` and `prompt` generation info, shown on the image's info panel on the post. - **Video** — exactly 1 video, optionally with up to 3 accompanying images. - **Audio** — exactly 1 audio file (cannot mix with other media). Supports `song_name`, `genre`, `lyrics`, and dedicated `cover_image` art (the cover is NOT a media item — pass it in its own field). Each `media[].file` accepts a public URL, an uploaded-file URL from [`POST /v1/uploads`](/api-reference/files/upload-input-media), a data URI, or raw base64. **Size limits:** images 15 MB; audio 50 MB; video 100 MB — note that URL inputs are fetched with a 30 MB cap and uploads support up to 50 MB, so ~50 MB is the practical video ceiling via the API. **Limits & moderation:** - The API allows **5 posts per hour**, inside the site-wide limit of **20 posts per hour** per account across all surfaces (shares included) — both on top of the API's global rate limits. Exceeding any of them returns `429`. - Posting a byte-identical file you've already posted returns `409` with the existing post's id. - Posts published through the API carry a public **"via API"** label, like posts made with an Ava companion carry hers. - Image/video posts are **reviewed after publishing** (content rating and spam scoring). Feed and gallery visibility follow that review and your account standing; a post hidden by review is not refunded. **License:** pass `license` to choose the post's content license, exactly like the license picker in the site's post composer: `arr` (All Rights Reserved — the default), `cc-by` (Creative Commons Attribution 4.0) or `cc0` (Creative Commons Zero, public domain). Omit it and the post is published All Rights Reserved. A Creative Commons license is a permanent grant: **the license cannot be changed after publishing**, in either direction — deleting the post is the only way to stop offering it. An unrecognised value is treated as `arr` rather than rejected; the response's `license` always states what the post was published under. **Clan themes:** pass `theme_id` to enter the post in a live clan theme, exactly like choosing a theme in the site's post composer. [`GET /v1/themes`](/api-reference/social/list-themes-you-can-post-to) lists the live themes of the clans you own or have joined. Posting to a live theme of a clan you haven't joined joins you to that clan, as it does on the site. The theme is checked before anything is fetched or charged: an unknown id returns `404 theme_not_found`, a theme that hasn't started or has ended returns `400 theme_not_active`, and a clan you're banned from (or whose owner you have a block with) returns `403 theme_not_permitted`. Theme entries cost the same 10 credits as any post. operationId: createPost requestBody: content: application/json: schema: properties: content: description: Optional caption (max 2000 characters). type: string cover_image: description: >- Audio posts only — cover art for the track (a public URL, an uploaded-file URL, a data URI, or raw base64; image, max 15 MB). Passed as its own field, never as a `media` item (audio posts can't mix media). type: string genre: description: >- Audio posts only — one of the site's canonical music genres (exact match). Omit to have the genre classified automatically after publishing. enum: - Pop - Rock - Hip-Hop & Rap - R&B & Soul - Electronic & Dance - Lo-fi & Chill - Ambient - Jazz - Classical - Country - Folk & Acoustic - Metal - Blues - Latin - K-Pop & J-Pop - Reggae - Soundtrack & Cinematic - Other type: string license: default: arr description: >- Content license for the post: `arr` (All Rights Reserved), `cc-by` (CC BY 4.0) or `cc0` (CC0 1.0). Cannot be changed after publishing. enum: - arr - cc-by - cc0 type: string lyrics: description: Audio posts only. type: string media: description: >- The post's media items, in display order. One of: 1-6 images; OR exactly 1 video plus up to 3 images; OR exactly 1 audio file (audio can't mix with other media). items: properties: file: description: >- Public URL, uploaded-file URL, data URI, or raw base64. type: string model: description: >- Images only — the model that generated this image, shown on the image's info panel (e.g. `seedream-5.0-pro`). maxLength: 100 type: string prompt: description: >- Images only — the prompt that generated this image, shown on the image's info panel. maxLength: 10000 type: string type: description: >- Optional declared kind — validated against the file's actual content. enum: - image - video - audio type: string required: - file type: object maxItems: 6 minItems: 1 type: array song_name: description: Audio posts only — track title. type: string theme_id: description: >- Optional — enter the post in this live clan theme. Get ids from [`GET /v1/themes`](/api-reference/social/list-themes-you-can-post-to) (or the number in a `budgetpixel.com/themes/` URL). Works with any media type. example: 75 minimum: 1 type: integer required: - media type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreatePostResponse' description: Post published. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': content: application/json: schema: $ref: '#/components/schemas/Error' description: Insufficient credits to publish. '403': $ref: '#/components/responses/Forbidden' '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: '`theme_not_found` — no theme with that `theme_id`.' '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Duplicate media — you already posted a byte-identical file. '429': $ref: '#/components/responses/TooManyRequests' components: schemas: CreatePostResponse: description: A published post. properties: credits_charged: example: 10 type: integer id: description: The post id. type: integer license: description: The content license the post was published under. enum: - arr - cc-by - cc0 example: arr type: string media_type: enum: - image - video - audio type: string moderation: description: >- Image/video posts are rated after publish; feed visibility follows the review. example: pending type: string theme: description: Present only when the post was entered in a theme (`theme_id`). properties: id: example: 75 type: integer title: example: Neon Noir type: string url: example: https://budgetpixel.com/themes/75 format: uri type: string type: object url: description: Public URL of the post. example: https://budgetpixel.com/p/12345 format: uri type: string type: object Error: properties: error: properties: code: description: Stable machine-readable code. example: model_not_available type: string message: type: string type: description: Error category. example: invalid_request_error type: string required: - type - code - message type: object required: - error type: object ModerationBlocked: description: >- Returned (with HTTP 400) when the input content moderation gate blocks a generation request. The block is a property of the request's prompt or input media — reword the prompt or change the input and retry. Branch on `restriction_reason`, which is stable and machine-readable. properties: error: description: Human-readable explanation of the block. type: string restriction_reason: description: Stable machine-readable block reason. enum: - input_csam - input_explicit_adult - input_upload_nudity - input_celebrity_likeness - strict_model_nsfw type: string required: - error - restriction_reason type: object responses: BadRequest: content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ModerationBlocked' description: >- The request was malformed, referenced an unavailable model, or was blocked by input content moderation (moderation blocks carry a `restriction_reason` — see ModerationBlocked). Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Missing or invalid API key. Forbidden: content: application/json: schema: $ref: '#/components/schemas/Error' description: >- Authenticated but not permitted (plan gate, ownership, account restriction). Content-moderation blocks are 400, not 403. TooManyRequests: content: application/json: schema: $ref: '#/components/schemas/Error' description: Rate or queue limit reached. Retry after a short delay. securitySchemes: ApiKeyAuth: bearerFormat: bpx_live_* description: 'API key as a bearer token: Authorization: Bearer bpx_live_xxx' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.