Chapter 18 — Files (Creative Uploads)

The POST /upload endpoint accepts a creative asset and returns a file_id for use in creative.file_id (Chapter 17).

Two request formats

A. JSON with a remote URL

Use this when the asset already lives on a publicly accessible URL.

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" }'

B. Multipart with a binary file

Use this when uploading a local file directly.

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

Response

Both formats return the same shape:

{ "file_id": "file_901" }

Using the uploaded file

Pass the file_id on creative.file_id when creating or updating an ad.

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"
    }
  }'

Reusability

A file_id is reusable across ads. Upload once, reference many times. This matters at scale:

Running the same image across multiple ad-group variants? One file_id.
Testing different titles against a fixed image? One file_id, multiple ads.
Refreshing copy without changing imagery? Reuse the existing file_id, only the title/body change.

Where the asset is served

Once an ad references a file_id, the asset is served from https://cdn.openai.com/ads/{file_id}.png (the URL appears in creative.image_url on ad responses). You do not host the image — OpenAI’s CDN does.

Format and size

OpenAI’s documented examples use PNG. The endpoint accepts PNG and JPG variants in practice; for definitive specs (max dimensions, file size, aspect ratio), check the OpenAI advertiser portal directly — these specs evolve and aren’t in the reference docs.