openapi: 3.2.0 info: title: Budgetpixel Social API version: '2026-06-20' contact: email: support@budgetpixel.com name: BudgetPixel Support description: 'Operations tagged Social across 2 of this provider''s published API definitions: budgetpixel-openapi.yaml, budgetpixel-openapi.yaml. Each path carries the servers of the definition it was published in.' servers: - description: Production url: https://api.budgetpixel.com/v1 security: - ApiKeyAuth: [] tags: - description: Publish posts to your BudgetPixel feed name: Social paths: /posts: post: description: "Publish a post to your public BudgetPixel feed — the same posts you create on the\nsite, so your local agent can publish on your behalf. **Synchronous**: the response\ncarries the live post's `id` and `url`.\n\n**Pricing: 10 credits per successful post**, charged only on success. Estimate via\n[`POST /v1/cost`](/api-reference/models/estimate-the-cost-of-a-request) with\n`{\"model\": \"create-post\"}`.\n\n**Media composition** (one of):\n- **Images** — 1 to 6 images. Each image can optionally carry `model` and\n `prompt` generation info, shown on the image's info panel on the post.\n- **Video** — exactly 1 video, optionally with up to 3 accompanying images.\n- **Audio** — exactly 1 audio file (cannot mix with other media). Supports\n `song_name`, `genre`, `lyrics`, and dedicated `cover_image` art (the cover is\n NOT a media item — pass it in its own field).\n\nEach `media[].file` accepts a public URL, an uploaded-file URL from\n[`POST /v1/uploads`](/api-reference/files/upload-input-media), a data URI, or raw\nbase64. **Size limits:** images 15 MB; audio 50 MB; video 100 MB — note that URL\ninputs are fetched with a 30 MB cap and uploads support up to 50 MB, so ~50 MB is\nthe practical video ceiling via the API.\n\n**Limits & moderation:**\n- The API allows **5 posts per hour**, inside the site-wide limit of **20 posts\n per hour** per account across all surfaces (shares included) — both on top of\n the API's global rate limits. Exceeding any of them returns `429`.\n- Posting a byte-identical file you've already posted returns `409` with the\n existing post's id.\n- Posts published through the API carry a public **\"via API\"** label, like posts\n made with an Ava companion carry hers.\n- Image/video posts are **reviewed after publishing** (content rating and spam\n scoring). Feed and gallery visibility follow that review and your account\n standing; a post hidden by review is not refunded.\n" 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 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 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' '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Duplicate media — you already posted a byte-identical file. '429': $ref: '#/components/responses/TooManyRequests' summary: Publish a post tags: - Social servers: - description: Production url: https://api.budgetpixel.com/v1 components: responses: 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. 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). TooManyRequests: content: application/json: schema: $ref: '#/components/schemas/Error' description: Rate or queue limit reached. Retry after a short delay. Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Missing or invalid API key. schemas: 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 CreatePostResponse: description: A published post. properties: credits_charged: example: 10 type: integer id: description: The post id. type: integer 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 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 securitySchemes: ApiKeyAuth: bearerFormat: bpx_live_* description: 'API key as a bearer token: Authorization: Bearer bpx_live_xxx' scheme: bearer type: http x-refined-from: - budgetpixel-openapi.yaml - budgetpixel-openapi.yaml