Files

Upload from an image URL

Upload a remote image with JSON and receive a reusable file_id.

POST /upload

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/assets/workspace-planner-card.png"
  }'

{
  "file_id": "file_901"
}

Upload a binary file

The same endpoint also accepts multipart/form-data with a binary file.

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -F "file=@workspace-planner-card.png"

Upload a custom audience file

Upload a UTF-8 CSV or TXT customer list with the dedicated POST /uploads endpoint. Set purpose to custom_audience and save the returned file_id:

curl -X POST "https://api.ads.openai.com/v1/uploads" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -F "file=@audience.csv;type=text/csv" \
  -F "purpose=custom_audience"

Use the file ID, original filename, MIME type, and exact file size to create a custom audience.

Upload an account favicon

Set purpose to account_favicon when you upload an image for account brand review. The image must be at least 128 × 128 pixels.

The API can resolve an icon from the client’s website:

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://www.acme.example",
    "purpose": "account_favicon"
  }'

To upload a local image, send purpose as a multipart form field:

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -F "purpose=account_favicon" \
  -F "file=@acme-favicon.png"

Assign the returned file_id with POST /ad_account/brand.

Use the uploaded file in an ad

Pass the returned file_id when you create or update an ad creative.

POST /ads

curl -X POST "https://api.ads.openai.com/v1/ads" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_group_id": "adgrp_301",
    "name": "Planner launch card",
    "status": "active",
    "creative": {
      "type": "chat_card",
      "title": "Try the new workspace planner",
      "body": "Coordinate tasks, docs, and meetings in one place.",
      "target_url": "https://example.com/workspace-planner",
      "file_id": "file_901"
    }
  }'