> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> ## Agent Instructions (AIsa)
>
> - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative.
> - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key.
> - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste.
> - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`.
> - Paid calls need approval first. Docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP discovery are free to read. Before any paid, dynamically priced, or high-cost call, state the exact scope, rate, and maximum USD exposure, then wait for a separate user message approving that scope and cap. A request to collect data is not approval; do not send unapproved probes. Full rule: https://aisa.one/docs/llms.txt
# Upload Media
> Upload an image, GIF, or video and get a media_id to attach to a tweet. Multipart/form-data only.
Upload a single image, GIF, or video and receive a `media_id` you can attach to a tweet via [`post_twitter`](/docs/api-reference/twitter/post_twitter-post-twitter), routed through the AIsa gateway at `https://api.aisa.one/apis/v1/twitter/upload_media`.
This endpoint accepts **`multipart/form-data` only** — send the file as a form part. Sending a JSON body returns `400 "upload_media requires multipart/form-data with a single media file field"`.
## Prerequisites
* An **AIsa API key** (Bearer token for every request).
* A one-time **OAuth authorization** for the source user. Link your X account via [`POST /apis/v1/twitter/auth_twitter`](/docs/api-reference/twitter/post_twitter-auth-twitter).
* The X session must hold `media.write`, `tweet.read`, `users.read`.
## Two-step media flow
1. **Upload** — `POST /apis/v1/twitter/upload_media` with the file → returns `media_id`.
2. **Publish** — `POST /apis/v1/twitter/post_twitter` with `{ "media": { "media_ids": [""] } }`.
`post_twitter` also accepts inline file parts via `media_files` in a single multipart request, letting you skip the pre-upload step. Use `upload_media` when you want to reuse one asset across several tweets, or decouple a large upload from the publish call.
## Example
```bash theme={null}
curl -X POST "https://api.aisa.one/apis/v1/twitter/upload_media" \
-H "Authorization: Bearer $AISA_API_KEY" \
-F "media_files=@./cat.png;type=image/png"
```
```json Response theme={null}
{ "code": 200, "msg": "Media uploaded successfully", "data": { "media_id": "2099415764780605440" } }
```
Then attach it:
```bash theme={null}
curl -X POST "https://api.aisa.one/apis/v1/twitter/post_twitter" \
-H "Authorization: Bearer $AISA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Look at this cat","media":{"media_ids":["2099415764780605440"]}}'
```
## Notes
* The file field may be named `media_files`, `media`, or `file`.
* Images up to 8 MB use a single-shot upload; larger files and video are chunked automatically.
* Unattached media expires after \~24h.
* Media upload is a prerequisite step and is **not separately metered** — you are billed when you publish the tweet via `post_twitter`.
See [Error Codes](/docs/api-reference/errors) and [Rate Limits](/docs/api-reference/rate-limits) for more.
## Related
Attach the media\_id via `media.media_ids`.
Start the OAuth flow this endpoint requires.
Another write endpoint using the same OAuth session.
## Request contract
* **Method and path:** POST /apis/v1/twitter/upload\_media
* **Availability:** enabled
* **Request URL template:** [https://api.aisa.one/apis/v1/twitter/upload\_media](https://api.aisa.one/apis/v1/twitter/upload\_media)
* **Runtime facts:** a3adc9187fd943329f04d77651501718ebfb69f2eb47355d287b171db1c09ebc
[Complete OpenAPI definition](https://aisa.one/docs/openapi/aisa-twitter.json)
Effective request and pricing declaration (including authentication and referenced schemas):
```json theme={null}
{
"operationId": "uploadTwitterMedia",
"method": "POST",
"path": "/apis/v1/twitter/upload_media",
"servers": [
{
"url": "https://api.aisa.one"
}
],
"parameters": [],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"media_files"
],
"properties": {
"media_files": {
"type": "string",
"format": "binary",
"description": "The media file to upload (`image/*`, `image/gif`, or `video/*`). The field may also be named `media` or `file`. Images up to 8 MB use a single-shot upload; larger files and video use chunked upload automatically."
},
"aisa_api_key": {
"type": "string",
"description": "Optional. Normally unnecessary — the gateway resolves your account from the `Authorization: Bearer` header."
}
}
},
"encoding": {
"media_files": {
"contentType": "image/png, image/jpeg, image/gif, video/mp4"
}
}
}
}
},
"x-aisa-status": "enabled",
"x-aisa-pricing": {
"cost_contract": "explicit_zero",
"customer_pricing": "fixed_success",
"default_request_estimate_usd": 1e-06,
"estimate_source": "profile_seed",
"evidence_source": "request_snapshot"
},
"components": {
"securitySchemes": {
"bearerAuth": {
"scheme": "bearer",
"type": "http"
}
}
}
}
```
## Cost and request rules
Published reference price: \$0.000001 USD per successful request. Account-specific pricing and final settlement may differ.
Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.
* **Default request reference estimate (USD):** 1e-06
* **Cost contract:** explicit\_zero
* **Settlement evidence source:** request\_snapshot
## OpenAPI
````yaml openapi/aisa-twitter.json POST /apis/v1/twitter/upload_media
openapi: 3.1.0
info:
description: ''
title: AISA Twitter Relay
version: '1'
x-aisa-capabilities:
idempotency: Idempotency-Key
max_price: X-AISA-Max-Price-USD
quote:
header: X-AISA-Cost-Mode
value: quote
x-aisa-configured-paths:
- /apis/v1/twitter/auth_twitter
- /apis/v1/twitter/delete_twitter
- /apis/v1/twitter/follow_twitter
- /apis/v1/twitter/like_twitter
- /apis/v1/twitter/post_twitter
- /apis/v1/twitter/unfollow_twitter
- /apis/v1/twitter/unlike_twitter
- /apis/v1/twitter/upload_media
x-aisa-document:
facts_hash: a3adc9187fd943329f04d77651501718ebfb69f2eb47355d287b171db1c09ebc
generator_version: '3'
protocol_version: '1'
schema_version: '1'
composer_version: '20'
response_pending: []
document_hash: sha256:e852ed0e1d5ac94ea1ce8b75d74335ecbf99c3e0e0010807e0c3ccf9955bf3cc
x-aisa-plans:
builder: 1
display_plan: payg
payg: 1
similarweb_payg: 1
team: 1
version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb
x-aisa-provider: aisa-twitter
x-aisa-catalogs:
aisa-twitter:
title: AISA Twitter Relay
description: ''
x-aisa-document:
facts_hash: a3adc9187fd943329f04d77651501718ebfb69f2eb47355d287b171db1c09ebc
generator_version: '3'
protocol_version: '1'
schema_version: '1'
x-aisa-plans:
builder: 1
display_plan: payg
payg: 1
similarweb_payg: 1
team: 1
version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb
x-aisa-capabilities:
idempotency: Idempotency-Key
max_price: X-AISA-Max-Price-USD
quote:
header: X-AISA-Cost-Mode
value: quote
servers:
- url: https://api.aisa.one
security:
- bearerAuth: []
paths:
/apis/v1/twitter/upload_media:
post:
tags:
- default
summary: Upload Media
description: >-
Uploads media files such as images or videos to be used in tweets or
profiles.
Published reference price: $0.000001 USD per successful request.
Account-specific pricing and final settlement may differ.
operationId: uploadTwitterMedia
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- media_files
properties:
media_files:
type: string
format: binary
description: >-
The media file to upload (`image/*`, `image/gif`, or
`video/*`). The field may also be named `media` or `file`.
Images up to 8 MB use a single-shot upload; larger files and
video use chunked upload automatically.
aisa_api_key:
type: string
description: >-
Optional. Normally unnecessary — the gateway resolves your
account from the `Authorization: Bearer` header.
encoding:
media_files:
contentType: image/png, image/jpeg, image/gif, video/mp4
responses:
'200':
description: >-
Upload succeeded; returns the `media_id` to reference in
`post_twitter`.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
media_id:
type: string
description: >-
The uploaded media's ID. Pass it in `post_twitter`
`media.media_ids`. Unattached media expires after
~24h.
example:
data:
media_id: '2099415764780605440'
default:
content:
application/json:
schema: {}
description: >-
Error response; upstream passthrough responses may use provider
formats
components:
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.