Skip to main content
POST
/
v1
/
contents
curl --request POST \
  --url https://api.valyu.ai/v1/contents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "urls": [
    "https://example.com/article1",
    "https://example.com/article2"
  ],
  "response_length": "medium",
  "max_price_dollars": 0.1,
  "extract_effort": "auto",
  "summary": false
}
'
{
  "success": true,
  "error": null,
  "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
  "results": [
    {
      "title": "AI Breakthrough in Natural Language Processing",
      "url": "https://example.com/article1?utm_source=valyu",
      "content": "# AI Breakthrough in Natural Language Processing\n\nThis article discusses recent breakthroughs in natural language processing, including advances in large language models and their applications in various industries...",
      "description": "Latest AI developments in NLP technology",
      "source": "web",
      "price": 0.002,
      "length": 12840,
      "data_type": "unstructured",
      "image_url": {
        "main": "https://example.com/hero-image.jpg"
      }
    }
  ],
  "urls_requested": 1,
  "urls_processed": 1,
  "urls_failed": 0,
  "total_cost_dollars": 0.002,
  "total_characters": 12840
}

Authorizations

​
x-api-key
string
header
required

Your Valyu API key. Get one at platform.valyu.ai

Body

application/json
​
urls
string<uri>[]
required

List of URLs to process (maximum 10 URLs per request)

Required array length: 1 - 10 elements
Example:
[
  "https://example.com/article1",
  "https://example.com/article2"
]
​
response_length
default:short

Content length configuration:

  • "short": 25,000 characters (good for summaries)
  • "medium": 50,000 characters (good for articles)
  • "large": 100,000 characters (good for academic papers)
  • "max": No character limit
  • Custom integer: Specific character limit
Available options:
short,
medium,
large,
max
Example:

"medium"

​
max_price_dollars
number<float>

Maximum cost limit in dollars for the entire request. If not specified, defaults to 2x the estimated cost.

Required range: x >= 0
Example:

0.1

​
extract_effort
enum<string>
default:normal

Processing effort level:

  • "normal": Fastest extraction speed (Fastest)
  • "high": Enhanced extraction with better content quality and reliability (Slower)
  • "auto": Automatically chooses the right effort level (Slowest)
Available options:
normal,
high,
auto
Example:

"normal"

​
screenshot
boolean
default:false

Request page screenshots. When true, each result will include a screenshot_url field containing a pre-signed URL to a screenshot image of the page. Screenshots are captured during page rendering.

Example:

false

​
summary
default:false

Toggle AI processing (false is default)

Example:

true

Response

All URLs processed successfully

​
success
boolean

Whether the request was successful

Example:

true

​
error
string | null

Error message if any issues occurred

Example:

null

​
tx_id
string

Unique transaction ID for tracking and support

Example:

"tx_12345678-1234-1234-1234-123456789abc"

​
results
object[]

Array of processed content results

​
urls_requested
integer

Number of URLs submitted in the request

Required range: 1 <= x <= 10
Example:

2

​
urls_processed
integer

Number of URLs successfully processed

Required range: x >= 0
Example:

2

​
urls_failed
integer

Number of URLs that failed processing

Required range: x >= 0
Example:

0

​
total_cost_dollars
number

Actual cost charged (only for successful URLs)

Required range: x >= 0
Example:

0.004

​
total_characters
integer

Total characters across all processed results

Required range: x >= 0
Example:

25680