Upload Media

Upload an image, GIF, or video and get a media_id to attach to a tweet. Multipart/form-data only.

POST https://api.aisa.one/apis/v1/twitter/upload_media

Upload Media

cURL

curl --request POST \
  --url https://api.aisa.one/apis/v1/twitter/upload_media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'media_files=@example-file;type=image/png'

200

{
  "data": {
    "media_id": "2099415764780605440"
  }
}

Upload a single image, GIF, or video and receive a media_id you can attach to a tweet via 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.
• 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": ["<media_id>"] } }.

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

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"

Response

{ "code": 200, "msg": "Media uploaded successfully", "data": { "media_id": "2099415764780605440" } }

Then attach it:

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 and Rate Limits for more.

Related

Post a Tweet

Attach the media_id via media.media_ids.

Link an X Account

Start the OAuth flow this endpoint requires.

Like a Tweet

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
• Runtime facts: a3adc9187fd943329f04d77651501718ebfb69f2eb47355d287b171db1c09ebc

Complete OpenAPI definition

Effective request and pricing declaration (including authentication and referenced schemas):

{
  "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

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

media_files · file · required

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 · string

Optional. Normally unnecessary — the gateway resolves your account from the Authorization: Bearer header.

Response

200

application/json

Upload succeeded; returns the media_id to reference in post_twitter.

data · object

Show child attributes